DEV Community: Igor Proskurin

Using GNU toolchain for Windows kernel-mode drivers

Igor Proskurin — Mon, 03 Nov 2025 05:00:36 +0000

For a long time, I was curious about using GNU toolchain on Windows platforms, especially when it boils down to kernel-mode driver development. I like GNU toolchain (binutils, gcc, libstdc++). I use it for embedded development, but compiling, and especially linking binaries with GNU ld linker, has always been tricky. Why is it important? Microsoft Visual Studio is an excellent tool, but it is kind of obscure what is happening behind the scenes. Having free and open-source software toolchain even on a proprietary platform is a good thing (and avoid all the bloat from Visual Studio).

This time, it took me a while to figure out how to link a trivial kernel-mode driver, and this brief post is to document these findings.

Compiling GCC from sources for the mingw-w64 target is a topic for a different post (binutils is easy, though). So for these experiments I just used MSYS2 with UCRT64 environment. This painlessly bring you startup libraries (CRT), C standard library (mingw-w64), and compiler support libraries (libgcc and friends) together with libstdc++ if you use C++.

Running kernel-mode drivers on Windows requires a bunch of tricks (disabling secure boot, enabling test signing, and installing sysinternals). If you are not familiar with it, read a few introductory chapters from Windows Kernel Programming, or message me in the comments, and I will update this post with some details.

Driver Hello World

This is a typical "Hello World!" example for Windows kernel-mode drivers:

#include <ntddk.h>

static void test_driver_unload(PDRIVER_OBJECT driverObject);

NTSTATUS 
DriverEntry(PDRIVER_OBJECT driverObject, PUNICODE_STRING registryPath)
{
    UNREFERENCED_PARAMETER(registryPath);
    DbgPrint("Sample driver initialized successfully\n");

    driverObject->DriverUnload = test_driver_unload;

    return STATUS_SUCCESS;
}

void
test_driver_unload(PDRIVER_OBJECT driverObject)
{
    UNREFERENCED_PARAMETER(driverObject);
    DbgPrint("Driver unload called\n");
}

For tracing purposes, DbgPrint is provided by ntoskrnl.exe. DriverEntry is our entry point to the driver that is called by the kernel. test_driver_unload is our custom callback that should be called when the module is unloaded.

Using GNU ld for linking

Compiling into object code is easy, but linking is tricky. For reference of possible options, I used an example from ReactOS project. ReactOS is the only working (sort of) full reverse-engineered NT operating system kernel. It is a cool project. ReactOS GitHub repo has a collection of build options for kernel-mode drivers that can be carved out of CMake files.

Unfortunately, with options from ReactOs, I could not make my example fully working 64-bit Windows 11 -- driver loaded but refused to unload. The next repo that helped me with a list of options was Mingw64 Driver Plus Plus.

Finally, this combination of options provided a loadable and unloadable image:

gcc -std=gnu99 -Wall -Wextra -pedantic -shared -fPIC\
   -O0 -municode -nostartfiles -nostdlib -nodefaultlibs\
   -I/ucrt64/include/ddk -Wl,-subsystem,native \
   -Wl,--exclude-all-symbols,-file-alignment=0x200,-section-alignment=0x1000 \
   -Wl,-entry,DriverEntry -Wl,-image-base,0x140000000\
   -Wl,--dynamicbase -Wl,--nxcompat -Wl,--gc-sections\
   -Wl,--stack,0x100000\
   -o test_driver.sys test_driver.c -lntoskrnl

First time, I was also using -Wl,--wdmdriver options, but it was not helping. This mess can be organized in a Makefile:

TARGET = test_driver
OPT = -O0
CSTANDARD = -std=gnu99
DDK_INCLUDE_PATH = /ucrt64/include/ddk

CC = gcc
LD = ld
RM = rm -f
STRIP = strip
OBJDUMP = objdump -x

CFLAGS += -Wall
CFLAGS += -Wextra
CFLAGS += -pedantic
CFLAGS += -municode
CFLAGS += $(CTANDARD)
CFLAGS += $(OPT)

# Do not link startup, compiler support
# or C standard libraries.
CFLAGS += -nostartfiles
CFLAGS += -nostdlib
CFLAGS += -nodefaultlibs

CFLAGS += -fPIC
CFLAGS += -shared

# Include path to ntddk.h or wdm.h.
CFLAGS += -I$(DDK_INCLUDE_PATH)

LDFLAGS  = --exclude-all-symbols
LDFLAGS += --gc-sections
LDFLAGS += --dynamicbase
LDFLAGS += --nxcompat

LDFLAGS += -subsystem=native
LDFLAGS += -file-alignment=0x200
LDFLAGS += -section-alignment=0x1000
LDFLAGS += -image-base=0x140000000
LDFLAGS += --stack=0x100000

LDFLAGS +=-entry=DriverEntry

SRC = $(TARGET).c

OBJ = $(SRC:%.c=%.o)

LIBS  = -lntoskrnl
LIBS += -lhal

all: sys strip dump

dump: strip
    $(OBJDUMP) $(TARGET).sys

strip: sys
    $(STRIP) $(TARGET).sys

sys: $(TARGET).sys

.SECONDARY: $(TARGET).sys
.PRECIOUS: $(OBJ)

$(TARGET).sys: $(OBJ) 
    $(LD) $(LDFLAGS) -o $@ $(OBJ) $(LIBS)

%.o: %.c
    $(CC) $(CFLAGS) -c $< -o $@

clean:
    $(RM) $(TARGET).sys
    $(RM) $(SRC:%.c=%.o)

.PHONY: all sys clean strip dump

This Makefile can be found in my GitHub repo here.

Loading and unloading

On Windows 11, the driver also requires signing (using a Visual Studio tool). This is easy:

PS C:\Users\Igor> signtool sign /v /fd sha256 /n WDKTestCert test_driver.sys
The following certificate was selected:
    Issued to: WDKTestCert Igor,133660689149334675
    Issued by: WDKTestCert Igor,133660689149334675
    Expires:   Thu Jul 20 16:00:00 2034
    SHA1 hash: E76CFF2C68E75A85631906D4BC2F55A6D7B32597

Done Adding Additional Store
Successfully signed: test_driver.sys

Number of files successfully Signed: 1
Number of warnings: 0
Number of errors: 0

After that, we can use Service Control utility (it is also easy to write a custom loader based on Service Manager API):

sc create test_driver type= kernel binPath= C:\Users\Igor\test_driver.sys

Which creates a record in \HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\test_driver. After that, the driver can be started and stopped (and deleted if necessary):

PS C:\Users\Igor> sc start test_driver

SERVICE_NAME: test_driver
        TYPE               : 1  KERNEL_DRIVER
        STATE              : 4  RUNNING
                                (STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN)
        WIN32_EXIT_CODE    : 0  (0x0)
        SERVICE_EXIT_CODE  : 0  (0x0)
        CHECKPOINT         : 0x0
        WAIT_HINT          : 0x0
        PID                : 0
        FLAGS              :

PS C:\Users\Igor> sc stop test_driver

SERVICE_NAME: test_driver
        TYPE               : 1  KERNEL_DRIVER
        STATE              : 1  STOPPED
        WIN32_EXIT_CODE    : 0  (0x0)
        SERVICE_EXIT_CODE  : 0  (0x0)
        CHECKPOINT         : 0x0
        WAIT_HINT          : 0x0

The debug output (has to be enabled in the registry) shows tracing messages.

Summary

It is possible to link a simple Windows kernel-mode driver using GNU toolchain (mingw32-w64). For reference, source code for this example can be found in my GitHub repo here.

Generics in Rust: murky waters of implementing foreign traits on foreign types

Igor Proskurin — Tue, 04 Jun 2024 03:11:12 +0000

This post is about what bothered me for a while in generic Rust before I could clarify what's going on (sort of), namely, implementing foreign trait on foreign types, especially, in the context of Rust's way of "operator overloading".

We can't do it, or can we?

First, there is no mystery, right? The Rust Book is pretty clear on this matter.

But we can’t implement external traits on external types. For example, we can’t implement the Display trait on Vec<T> within our aggregator crate, because Display and Vec<T> are both defined in the standard library and aren’t local to our aggregator crate. This restriction is part of a property called coherence, and more specifically the orphan rule, so named because the parent type is not present.

So if we try to write something like this in the Playground:

impl From<usize> for f64 {
    // -- snippet --
}

the compiler immediately reminds us about this orphan rule

error[E0117]: only traits defined in the current crate can be implemented for primitive types

Nice and clear! Now, if we replace these lines with generics, the compiler error is different (and in a "slight" logical contradiction with the first error message), which hint that something is not so simple as advertised

impl<T, U> From<T> for U {
    // -- snippet --
}

error[E0210]: type parameter `U` must be used as the type parameter for some local type (e.g., `MyStruct<U>`)

When we look into a detailed explanation of error[E0210], we find our intuition was right:

When implementing a foreign trait for a foreign type, the trait must have one or more type parameters. A type local to your crate must appear before any use of any type parameters.

So we can do it in Rust, can't we? But what about The Book?

How can `nalgebra` do it?

Looking into reputable library crates such nalgebra also raises questions. Let's try, for example:

use nalgebra::Vector3;

fn main() {
   let v = Vector3::new(1.0, 2.0, 3.0);
   println!("{:?}", v * 3.0);
   println!("{:?}", 3.0 * v);
}

It compiles and produces what's expected, and everything look alight. But how is that possible?

The first expression is, of course, pretty standard: v * 3.0 requires implementing std::ops::Mul<f64> trait with Output = Vector3 on Vector3. However, 3.0 * v requires std::ops::Mul<Vector3> on the build-in type f64, which is nothing but implementing a foreign trait on a foreign type in direct violation of the The Book.

Looking into the nalgebra source code, we find that the first expression is implemented using generics

macro_rules! componentwise_scalarop_impl(
    ($Trait: ident, $method: ident, $bound: ident;
     $TraitAssign: ident, $method_assign: ident) => {
        impl<T, R: Dim, C: Dim, S> $Trait<T> for Matrix<T, R, C, S>
            where T: Scalar + $bound,
                  S: Storage<T, R, C>,
                  DefaultAllocator: Allocator<T, R, C> {
                //
                // -- snippet --
                //
            }
        }  
    }
);

The macro declaration is not so important in this case. More important is that right-multiplication by a scalar is generic, and all metavariables in the macro pattern simply bind to identifies.

Left multiplication by a scalar is completely different. It is not generic, macro pattern matcher binds to types with repletion patterns

macro_rules! left_scalar_mul_impl(
    ($($T: ty),* $(,)*) => {$(
        impl<R: Dim, C: Dim, S: Storage<$T, R, C>> Mul<Matrix<$T, R, C, S>> for $T
            // -- snippet --
    )*}
);

left_scalar_mul_impl!(u8, u16, u32, u64, usize, i8, i16, i32, i64, isize, f32, f64);

The last line explicitly instantiates implementations for built-in types.

So why is it different?

We can do what we can't

Finally, I found the answer in the RFC Book (RFC stands for Request For Comments).
RFC 2451 from 2018-05-30 that starts with the following lines:

For better or worse, we allow implementing foreign traits for foreign types.

That's it! That's the answer.

Then it becomes more interesting:

This change isn’t something that would end up in a guide, and is mostly communicated through error messages. The most common one seen is E0210. The text of that error will be changed to approximate the following:

Then follows the details of E0210 that I have already mentioned above. Together with RFC 2451 it clarifies a little bit when we can implement foreign traits for foreign types and when we cannon. One more details from these documents:

When implementing a foreign trait for a foreign type, the trait must have one or more type parameters. A type local to your crate must appear before any use of any type parameters. This means that impl ForeignTrait, T> for ForeignType is valid, but impl ForeignTrait> for ForeignType is not.

This works in the following example for left-scalar multiplication from my little library of generic Bezier curves that I used for illustration in previous posts

impl<T, const N: usize> Mul<Bernstein<T, f64, {N}>> for f64 where
            T: Copy + Mul<f64, Output = T>,
            [(); N]:
{
    // -- snippet --
}

In this example a foreign trait std::ops::Mul<T> specialized on a local generic type Bernstein<T, U, N> is implemented for a foreign type f64 similar to example above with left_scalar_mul_impl from nalgebra crate. Purely generic variant of this implementation

impl<T, U, const N: usize> Mul<Bernstein<T, U, {N}>> for U where
            T: Copy + Mul<U, Output = T>,
            U: Copy,
            [(); N]:
{
    type Output = Bernstein<T, U, {N}>;

    fn mul(self, rhs: Bernstein<T, U, {N}>) -> Self::Output {
        // -- snippet --
    }
}

gives already familiar compiler error E0210.

Summary

We can implement foreign traits on foreign types in Rust with caveats. However, this behavior is not in The Rust Book yet, and is communicated mostly through E0210 and RFCs. Pure generics do not work, which, according to RFC 2451, looks like a technical difficulty that may be revised in the future.

Generics in Rust: visualizing Bezier curves in a Jupyter notebook -- Part 3

Igor Proskurin — Fri, 31 May 2024 04:48:27 +0000

I decided to write a series posts about my experience with generic Rust, basically just to leave a trace of bread crumbs in my scattered studies. As a small practical problem, I chose to implement a library for manipulating generic Bezier curves that would work with different types and would wrap around primitive stack allocated arrays without dynamic binding and heap allocations. Here, there are some artefacts:

Experimenting with generics in Rust: little library for Bezier curves - part 1.
Generics in Rust: little library for Bezier curves -- Part 2.
and GitHub repository with source code and some examples.

In this post, I would briefly outline steps to visualize Bezier curves from my library by using Rust from a Jupyter notebook with Plotters.

Jupyter notebooks really revolutionized not only data science but scientific computing in general. Conceived originally for REPL (read-eval-print-loop) languages such as Julia, Python, and R, Jupyter notebooks are available now even for C++11, and, of course, Rust is not an exception.

First comes REPL - evxvr

A project for Rust REPL environment is a combination of letter evxvr (Evaluation Context for Rust). It contains Evcxr Jupyter kernel. I chose to follow the documentation and compile Jupyter kernel from Rust sources (which takes about 6 min on my laptop), and simply run in Microsoft Windows PowerShell

cargo install --locked evcxr_jupyter

This compiles the binary that can be found in $HOME\.cargo\bin. I already have Jupyter server installed as part of my Anaconda Python bundle. So after that, simply run

evcxr_jupyter --install

And that's all. Now, when I start Jupyter Server, I can choose Rust kernel, and use it from an interactive environment.

My overall impression from Rust notebooks is that they feel less smooth than, for example, Python notebooks (not surprising), but its pretty usable. Some extra work should be done to implement custom output for user-defined types.

Adding external dependencies

It is easy to add external dependencies directly to the Jupyter notebook. I just add the following lines to a notebook cell

:dep plotters = { version = "^0.3.0", default_features = false, features = ["evcxr", "all_series"] }
:dep num = {version = "0.4.3"}
:dep bernstein = { git = "https://github.com/sciprosk/bernstein.git" }

and then run it. It takes some visible time to run it for the first time, but after that it is fast. The last line adds my little library for Bezier curves directly from GitHub repo. Then I can put the following code into the next cell, and it works.

use bernstein::Bernstein;
use num::Complex;
use num::FromPrimitive;
use std::array;

// Create 2D Bezier control polygon in the complex plane
let p0 = Complex::new(0.0, 0.0);
let p1 = Complex::new(2.5, 1.0);
let p2 = Complex::new(-0.5, 1.0);
let p3 = Complex::new(2.0, 0.0);

// 2D Bezier curve in the complex plane parameterized with f32
let c: Bernstein<Complex<f32>, f32, 4> = Bernstein::new([p0, p1, p2, p3]);

// Just sample some points on the curve into array
let cs:[_; 11] = array::from_fn(
    |x| -> Complex<f32> {
        c.eval(f32::from_usize(x).unwrap() / 10.0)
    }
);

println!("{:?}", cs);

Plotting with Plotters

One of the crates that integrates evcxr is Plotters, which is used for ... well, you already know it.

Plotters can use different backends, and one them is evcxr_figure that allows to draw directly to the Jupyter notebook cells. The syntax is mostly self-explanatory.

use plotters::prelude::*;

let figure = evcxr_figure((800, 640), |root| {
    root.fill(&WHITE)?;
    let mut chart = ChartBuilder::on(&root)
        .caption("Cubic Bezier", ("Arial", 30).into_font())
        .margin(5)
        .x_label_area_size(30)
        .y_label_area_size(30)
        .build_cartesian_2d(-0.2f32..2.1f32, -0.8f32..0.8f32)?;

    chart.configure_mesh().draw()?;

    // Cubic Bezier curve
    chart.draw_series(LineSeries::new(
        // Sample 20_000 points
        (0..=20000).map(|x| x as f32 / 20000.0).map(|x| (c.eval(x).re, c.eval(x).im)),
        &RED,
    )).unwrap()
        .label("Cubic Bezier")
        .legend(|(x,y)| PathElement::new(vec![(x,y), (x + 20,y)], &RED));

    // Derivative, scaled down
    chart.draw_series(LineSeries::new(
        // Sample 20_000 points
        (0..=20000).map(|x| x as f32 / 20000.0).map(|x| (0.2 * c.diff().eval(x).re, 0.2 * c.diff().eval(x).im)),
        &BLUE,
    )).unwrap()
        .label("Derivative")
        .legend(|(x,y)| PathElement::new(vec![(x,y), (x + 20,y)], &BLUE));

    chart.configure_series_labels()
        .background_style(&WHITE.mix(0.8))
        .border_style(&BLACK)
        .draw()?;
    Ok(())
});
figure

This creates a 800x600 figure, fills it with white, sets the ranges to -0.2f32..2.1f32 along the horizontal axis, and to -0.8f32..0.8f32 along the vertical axis, and finally samples 20000 points of the cubic Bezier curve and its parametric derivative (which is a quadratic Bezier curve -- scaled down to fit).

Summary

Interactive Rust is easy to install and straightforward to use. It requires more typing (sometimes struggling) than when using REPL in duck typed languages, which is a price of strong (and strict) type system. However, it is a cool tool for data visualization directly from Rust.

Generics in Rust: little library for Bezier curves -- Part 2

Igor Proskurin — Mon, 27 May 2024 14:10:20 +0000

Some time ago, I decided to write a couple of posts about my experience with generic programming in Rust. For me, when someone says generics, C++ template metaprogramming and Alexander Stepanov immediately pop in my mind. Rust is different. So it was interesting to see what's going on out there, which motivated my original interest.

Learning by doing is the best for quick hands-on, so I decided to write a little generic numeric library for manipulating Bezier curves (polynomials in the Bernstein basis) that is (i) uses static dispatch (and no heap allocation calls), and (ii) can be used with different types for specifying Bezier control polygon: reals, rationals, complex, and, in general, something that implements standard vector-space operations.

What I learned is that writing generic libraries in Rust is not a piece of cake. There are two major facts that contribute into this: (i) Rust's explicit safety-oriented type system, and (ii) the absence of decent support of generic constant expressions in stable Rust. So what I am writing about here is based on Rust Nightly.

So before we take of, there is a couple of previous posts

And the Github repo that contains examples from these posts, some tests, and maybe even some demos, if I will manage to add them in nearby future.

First steps

First, make sure we use the unstable rust build. I will just set it up for all repositories with rustup default nightly, but it is possible to apply it to a folder with rustup override set nightly. After that:

PS > rustc --version
rustc 1.80.0-nightly (1ba35e9bb 2024-05-25)

and we also make sure that we include the following lines in our crate

#![allow(incomplete_features)]
#![feature(generic_const_exprs)]

As I briefly outlined here, Rust currently does not support generic constant expression in its type system. It is not that something is wrong with it in general, it is just not implemented due to technical difficulties. This is considered to be an unstable feature.

To describe a generic Bezier curve c(u) = (x(u), y(u), z(u), ...), I basically wrap a primitive array type [T; N] into a struct

pub struct Bernstein<T, U, const N: usize> {
    coef: [T; N],
    segm: (U, U),
}

that contains a generic type parameter T for Bezier control polygon, type parameter U for curve parametrization, and a generic constexpression parameter N for the number of basis polynomials (or just the size of the Bezier control polygon). For example, a cubic Bezier curve should have four points in its control polygon, i. e. N = 4. The curve is always parameterized on 0 <= u <= 1, so right now segm is defaulted to (0, 1).

Some more details can be found in my previous post. In this post, I would like to discuss how implement generic methods on this type that would leverage generic constant expressions on the size of the control polygon N.

Implementing eval-method

The first method to do is, of course, to implement eval() method to find a point on the curve at some value of the parameter u, so that we can write something like this

let p0 = Complex::new(0.0, 0.0);
let p1 = Complex::new(2.5, 1.0);
let p2 = Complex::new(-0.5, 1.0);
let p3 = Complex::new(2.0, 0.0);

// Define cubic Bezier curve in the complex plane.
let c: Bernstein<Complex<f32>, f32, 4> = Bernstein::new([p0, p1, p2, p3]);

let p = c.eval(0.5); // point on a curve of type Complex<f32>

This part is easy, and can be done even in stable Rust. I just use the De Casteljau's algorithm

impl<T, U, const N: usize> Bernstein<T, U, N> where
    T: Copy + Add<T, Output = T> + Sub<T, Output = T> + Mul<U, Output = T>,
    U: Copy + Num,
{
    pub fn eval(&self, u: U) -> T {
        // -- snippet --
        // De Casteljau's algorithm
    }
}

Trait bounds on types are quite transparent. I require Copy trait to make my life easier when manipulating mathematical expressions, type U should be a number, which is required by num::Num trait. This is especially useful because Num trait requires generic One and Zero traits, which provide methods such as U::zero() and U::one(). Type T is required to implement vector space operations of addition, subtraction, and right-hand-side multiplication by a variable of type U with the result of being of type T (Mul<U, Output = T>).

Implementing diff and integ methods

The next step is to implement generic diff() and integ() methods to find the parametric derivative of the Bezier curve dc(u)/du, and the integral with respect to parameter u. That's where generic constant expression come into play.

The problem is that our methods should take an array of control points [T; N] of size N as an input, and return an array of size N - 1 for diff() or N + 1 for integ() as output nicely wrapped into our custom Bernstein type so that the signatures of the functions should be like these:

fn diff(&self) -> Bernstein<T, U, {N - 1}> {}

// c: T -- is the initial point to fix the constant of integration.
fn integ(&self, c: T) -> Bernstein<T, U, {N + 1}> {}

And stable Rust does not allow us to do that. Using generic_const_exprs feature, it becomes possible, as we shall see shortly.

Another difficulty is related to Rust's explicit type system. In these methods, the size of the array N becomes a part of mathematical expressions in the diff() and integ() algorithms. Rust requires the size of the array to be of a machine-dependent pointer size usize (which totally make sense but it is not generic). Converting from usize to other type is not considered to be a safe operation so I have to rely on third party traits for that purpose, such as num::FromPrimitive trait that is implemented for usize in the num crate. Otherwise, multiplying and expression of type, let's say, f64, by N is not defined.

Having this in mind, let's discuss diff() method (implementing integ() is similar and may be found in the repo):

impl<T, U, const N: usize> Bernstein<T, U, N> where
    T: Copy + Add<T, Output = T> + Sub<T, Output = T> + Mul<U, Output = T>,
    U: Copy + Num + FromPrimitive,
{
    pub fn diff(&self) -> Bernstein<T, U, {N - 1}> where
        [(); N - 1]:
    {
        let coef: [T; N - 1] = array::from_fn(
            |i| -> T {
                (self.coef[i + 1] - self.coef[i]) *
                (U::from_usize(N - 1).unwrap() / (self.segm.1 - self.segm.0))
            }
        );

        Bernstein {
            segm: self.segm,
            coef: coef,
        }
    }
}

Here, there is a couple of new details. First, I require type U to be bounded by FromPrimitive trait that allows to convert from usize to U in a generic environment by calling U::from_usize(N - 1).unwrap(). Second is that there is new bound [(); N - 1]: which is required by generic_const_exprs feature

We currently use where [(); expr]: as a way to add additional const wf bounds. Once we have started experimenting with this it is probably worth it to add a more intuitive way to add const wf bounds.

The bounds on T type is basically the same as in the eval() method.

Now, we can find a derivative type from a basic type, by using for example the following

// Define cubic Bezier curve in the complex plane.
let c: Bernstein<Complex<f32>, f32, 4> = Bernstein::new([p0, p1, p2, p3]);

// Get the derivative, or hodograph curve at u = 0.2.
let d = c.diff().eval(0.2); // `d` is of type Complex<f32>

Generic product of two polynomials

The next example is a product of two polynomials of order N - 1 and M - 1 (the size of arrays of coefficients is N and M respectively). This is a little bit more involved since it has to take the array [T; N] as an input, multiply it by [T; M] and the type of output should be [T; M + N - 1]. For example, multiplying a polynomial of the third order (N = 4) by a second-order polynomial (N = 3) should give a quintic polynomial (N = 6).

The implementation may looks like this:

impl<T, U, const N: usize, const M: usize>
Mul<Bernstein<T, U, {M}>> for Bernstein<T, U, {N}> where
    T: Copy + Add<Output = T> + Sub<Output = T> + Mul<Output = T> + Mul<U, Output = T>,
    U: Num + FromPrimitive,
    [(); N]:,
    [(); M]:,
    [(); N + M - 1]:
{
    type Output = Bernstein<T, U, {N + M - 1}>;

    fn mul(self, rhs: Bernstein<T, U, {M}>) -> Self::Output {
        let mut coef = [self.coef[0] - self.coef[0]; N + M - 1];

        // -- snippet --
        // actual algorithm

        Bernstein {
            coef: coef,
            segm: self.segm,
        }
    }
}

The required operation is specified by Mul<Bernstein<T, U, {M}>> in the impl, and the resulting type should be type Output = Bernstein<T, U, {N + M - 1}>.

Another subtle moment is that I have to initialize the array in the body of the function mul() because Rust does not allow to use uninitialized variables (remember old plain C89? -- who cared about initializing all the variables). One way to do it is to put a trait bound on T to implement T::zero() that can be used as an initial value. In this case, I chose a workaround instead (may change it later) which is to require subtraction Sub<Output = T> and use self.coef[0] - self.coef[0] as a kind of generic zero.

Note that generic-const-exprs require additional trait bounds to be imposed for each of the array types we use [(); N]:, [(); M]:, [(); N + M - 1]:.

Now, it possible to write

let p: Bernstein<f64, f64, 3> = Bernstein::new([0.0, 2.0, 1.0]);
let q: Bernstein<f64, f64, 4> = Bernstein::new([1.0, 2.0, 0.0, 0.0]);

// Quintic polynomial with real coefficient 
let c = p * q;

Summary

Generic constant expressions in Rust give the flexibility of implementing generic types which size is known at compile time. So far, using an unstable Rust nightly 1.80, I didn't notice any issues with using generic-const-exprs feature.

Experimenting with generics in Rust: little library for Bezier curves - part 1

Igor Proskurin — Mon, 20 May 2024 20:17:57 +0000

Not so long time ago, I decided to look into one aspect of Rust programming language that is of a certain personal interest for me --- generic programming. Generic (or template) programming is one of my favorite paradigms in modern C++, and it was certainly worth trying how it is currently supported in a shiny "new" language such as Rust. I actually liked what I found out there. After struggling a little with Rust's strict type system, I even started to appreciate its philosophy of being explicit.

This post is an attempt to document some of my experiments with generics in Rust. As time goes by, I found that it is quite handy to leave some traces and artefacts so that there is a place go back after some time. This post is basically written to my future self and maybe for someone who finds it useful.

Code, examples, tests, and some other documentation for this post can be in the repo.

Tiny generic numeric library: requirements

The best way of learning is by doing, and there is no other way... So let's try write a tiny numeric library which nevertheless can be helpful elsewhere. The truth is that I have a similar library in C++ which I used quite a lot, so this would be a good test for Rust.

The requirements are as follows: write a library to manipulate a generic Bezier curve (or a polynomial in the Bernstein basis if you prefer it this way).

The control polygon of the Bezier curve should be of a generic type T which supports usual vector-space operations: it should support f32/f64, complex numbers, and vectors (in linear algebra sense).
The curve should be parameterized with a parameter of a generic type U, which should support f32/f64, rationals, and maybe arbitrary-precision floats.
The library should use stack memory allocation (no memory allocations on the heap), which means that the size of the control polygon is a compile-time constant N.
The library should implement usual vector space operations on the control polygon, eval(u) method to get the point on the curve of type T at the parameter value u of type U, diff()/integ() method to get new instance of the curve which is the derivative/integral of the current curve at every point, and multiplication of two polynomials of different degrees. The last three methods are especially problematic because they should return an instance of a different size: N-1, N + 1, or N + M in general.

So these are all the requirement for now. Let's try it...

Generic Bezier curves: design considerations

The first thing I stumbled upon while tying to implement these requirements was the lack of support for generic constant expressions in Rust, which I briefly summarized in my previous post.

In general, it is a known problem, and since I don't expect this example to ever reach a productionable stage, I decided to go with Rust nightly and use a highly experimental generic_const_exprs feature.

#![allow(incomplete_features)]
#![feature(generic_const_exprs)]

And I compile it with rustc 1.80.0-nightly (d84b90375 2024-05-19).

Second difficulty for designing generics is Rust's explicit type system, which does very little for you if you want automatic type promotions and conversions. This is actually a feature not a bug, and part of Rust's philosophy of being explicit. It helps to ensure that the program is correct, but makes life harder...

For example, I want to store coefficients internally in the array of type [T; N], where N is constant type parameter. In Rust, N must be of the platform-dependent pointer-size type usize, and there is a little you can do to convert usize to other types using core language. This is of course for safety reasons, but in a generic environment, in conjunction with direct prohibition for implementing external traits for standard types, I either have to implement conversion manually, or rely on third party crates such as conv for example.

There is also an interesting crate generic-array but we are not going this path here.

After experimenting a little bit with different dependencies, I decided to depend on num crate, that exposes some new types for e.g. rationals and complex numbers, and also has extended type conversions in num::cast including handy FromPrimitive trait.

[dependencies]
num = "0.4.3"

Finally, let me introduce our type for a generic Bezier curve.

pub struct Bernstein<T, U, const N: usize> {
    coef: [T; N],
    segm: (U, U),
}

We have two generic types: T for control polygon, and U for the curve parameter (which I decided to make a part of the type), and one constant generic parameter for the size of the control polygon (the order of the curve is N - 1, i.e. a cubic Bezier has N = 4 control points).

The fields are private because the interval where Bezier curve is defined will be defaulted to (0, 1). Reason? It is hard to introduces anything that includes testing for equality or ordering in a numeric generic environment, because when it boils down to floating point math... well, you know.

Let's provide a simple accessors to get-set our type, and I leave it at this primitive level for now. Here, the type U is bounded by num::Num trait which includes convenient U::one() and U::zero() to set the default interval.

impl<T, U, const N: usize> Bernstein<T, U, N> where
    U: Num,
{

    /// Create new instance of a Bernstein polynomial from an array of
    /// coefficients in the Bernstein basis over the default interval (0, 1).
    pub fn new(coef: [T; N]) -> Bernstein<T, U, N> {
        Bernstein {
            coef: coef,
            segm: (U::zero(), U::one()),
        }
    }

    /// Return an array of coefficients for a polynomial in the Bernstein basis.
    pub fn coef(&self) -> &[T; N] {
        &self.coef
    }

}

Now, I have all the prerequisites for the next steps. It is possible to create an instance of the Bezier curve like this.

let p0 = Rational64::new(1, 5);
let p1 = Rational64::new(-3, 7);
let p2 = Rational64::new(4, 13);
let p3 = Rational64::new(-11, 17);

let c: Bernstein<Rational64, Rational64, 4> = Bernstein::new([p0, p1, p2, p3]);

Here, I specify the control polygon that has four rational control points, and rationals are also used for the curve parameterization on the interval (0, 1). The syntax is quite terse for my taste because the type is not automatically deduced from ::new(), and I have to spell out it explicitly in Bernstein<Rational64, Rational64, 4> but it's okay.

Next steps...

The next will be to implement a bunch of methods to evaluate the curve at a given point, generic differentiation and integration. The last two require generic_const_exprs, and that is where experimental features kick in.

Generic constant expressions: a future bright side of nightly Rust

Igor Proskurin — Fri, 17 May 2024 02:49:35 +0000

When I just started looking into generic programming in Rust, I was quite annoyed that something that is trivially done with C++ templates, cannot be done in Rust. You just can't... Generic traits are pretty cool, and certainly you can use const parameters in generics but if you just try

fn f<const N: usize>() -> [i32; 2 * N] {
    [2; 2 * N]
}

or even

struct s<const N: usize> {
    value: [i32; N + 1]
}

in both cases Ferris would be upset and we get error: generic parameters may not be used in const operations. So how can we implement something generic that is allocated on the stack or should we ask the operating system each time for memory on the heap?

Generic constant expression parameters

Unfortunately, there is no way of doing it in stable Rust. And we have to opt to a nightly build. Let's try it! I will use the latest nightly-x86_64-pc-windows-msvc. However, this feature seems to be here for while, and this may compile in other versions as well. Or maybe not... It looks like support of generic constant expressions is still highly experimental.

First look is into The Unstable Book. Well, it does not look informative but gives us some background from the rust-lang Github project-const-generics. It says:

The implementation is still far from ready but already available for experimentation.

Nice! That's exactly what we want...

Also, some interesting discussions and difficulties with implementing safe generic constant expressions can be found here and here.

Constant expression generic parameters in functions

Gear up and embrace for impact: rustup override set nightly, and we are in uncharted waters of experimental Rust.
Let's try again:

#![feature(generic_const_exprs)]
#![allow(incomplete_features)]
fn f<const N: usize>() -> [i32; 2 * N] {
    [2; 2 * N]
}

Now it compiles and let v = f::<2>() produces what we asked for [2, 2, 2, 2].

Constant expression generic parameters in types

Let's try a generic struct that wraps an array of a size known at compile time that is a constant expression.

#[derive(Debug)]
struct s<const N: usize> 
//where [i32; 2* N + 1]:
{
    value: [i32; 2 * N + 1]
}

Oops, this does not compile:

error: unconstrained generic constant
  --> src/main.rs:11:12
   |
11 |     value: [i32; 2 * N + 1]
   |            ^^^^^^^^^^^^^^^^
   |
help: try adding a `where` bound
   |
8  | struct s<const N: usize> where [(); 2 * N + 1]: 
   |                          ++++++++++++++++++++++

The problem here, as far as I understand from the discussion, is with the const-well-formdness. That is having a constant parameter N, how to verify that 2 * N + 1 is well-formed and won't, for example, overflow? So we need to add a bound.

We currently use where [(); expr]: as a way to add additional const wf bounds. Once we have started experimenting with this it is probably worth it to add a more intuitive way to add const wf bounds.

Adding this bound certainly helps, and now this compiles:

#![feature(generic_const_exprs)]
#![allow(incomplete_features)]

#[derive(Debug)]
struct s<const N: usize> 
where [(); 2 * N + 1]:
{
    value: [i32; 2 * N + 1]
}

fn main() {
    let v: s::<2> = s {value: [1, 2, 3, 4, 5]};
    println!("{:?}", v);
}

and gives s { value: [1, 2, 3, 4, 5] }. And if we replace this declaration with a wrong one let v: s::<3> = s {value: [1, 2, 3, 4, 5]}, it errors out with a meaningful error message

error[E0308]: mismatched types
  --> src/main.rs:12:31
   |
12 |     let v: s::<3> = s {value: [1, 2, 3, 4, 5]};
   |                               ^^^^^^^^^^^^^^^ expected `7`, found `5`
   |
   = note: expected constant `7`
              found constant `5`

Good!

What does not work...

It is not possible to define a recursive invocation of a function with a constant expression parameter like this (which is again trivial in C++ template metaprogramming):

fn factorial<const N: usize>() -> usize 
where [(); N - 1] {
    // ???
    factorial::<{N-1}>()
}

The problems is (1) how to stop the recursion, and (2) how to impose recursive generic-parameter bounds that the compiler asks us for.

Declaring internal constant expression parameters does not work either:

fn f<const N: usize>() -> [i32; 2 * N] {
    const M: usize = 2 * N;
    [2; 2 * N]
}

error[E0401]: can't use generic parameters from outer item
  --> src/main.rs:10:26
   |
9  | fn f<const N: usize>() -> [i32; 2 * N] {
   |            - const parameter from outer item
10 |     const M: usize = 2 * N;
   |                          ^ use of generic parameter from outer item
   |
   = note: a `const` is a separate item from the item that contains it

Summary

Let's hope that generic constant expressions will find their way in future safe and stable Rust. It will certainly help the expressiveness of the language when it comes to implementing generic libraries with static-sized aggregate types known at compile time.

WebAssembly: Building GUI for C++ libraries with Embind

Igor Proskurin — Sun, 17 Sep 2023 04:47:42 +0000

This post will probably not be very long of full of technical details. Instead, I would like to share some thought about using Embind -- a WebAssembly tool for binding high-level C++ code to JavaScript, and an example of an open-source project (that is of personal interest to me) that uses Embind to make GUI for its main product -- a numeric motion planning library. So if you are a C/C++ software/library developer, and you are looking for new tools to visualize, advertise or present you work, WebAssembly is something to thing about...

If you are new to WebAssembly, it is a relatively new web-technology that allows to compile code in languages such as C, C++ and Rust into a low-level assembly language that can be executed in a virtual stack-based machine inside a browser with reasonable productivity (compared to pure JavaSript). There are several resources that provide a good dive into WebAssembly basics:

MDN Web Docs: WebAssembly.
WebAssembly.org: nice collection of resouces.
Emscipten C/C++ to WebAssembly compiler.

What should I use it for?

What are benefits of using WebAssebmly with compiled languages like C/C++ or Rust?

You can run computationally intensive stuff client-side in browser, and have it on a web page. Think about fractal rendering, 3D graphics, or some physics simulations.
If you have library already written in C++ or C, it can be (in most cases) recompiled into WebAssembly bytecode with moderate efforts.

Of course, with benefits come limitations (Dialectics, eh?).

There are some limitations with what you can port to WebAssembly. Exceptions? Threads? Fancy memory layout?
To use it in a web browser, the code should be compiled with a dedicated compiler (e.g. emcc). It not possible to grab a production library.a compiled for x86-64 and just use it (would be nice, eh?).
Some work has to be done to bind data from web application to WebAssembly (read C/C++). Low-level memory management is clumsy, and tools like Embind are real help.

One possible application of WebAssembly is to provide a web access to a (low-level) numeric library API, so that users may turn the knobs in the browser and see what goes on without deploying this library to a hardware of making it a part of larger project. And in this post I will provide and example of a cool project in robotics that uses this approach. Of course, there is always an option to bind such code to Python or Julia which might make more sense in most cases, but sometimes a web app might be an interesting option.

A little bit about Embind

If you would like to jump start with C/C++ in WebAssembly, just install Emscipten SDK. It will install the emcc compiler and some basic environment. If you don't have XTerm/Bash at hand, don't worry -- it works in Windows PowerShell out of the box. Compiling C/C++ with emcc produces *.wasm binary file and optionally JavaScript module to embed *.wasm into a web application. Making it work in React may require a little bit more work. But that's pretty much it.

The problem is how to get something into WebAssembly internal memory space, and how to get stuff out of there. There is always low-level API at our disposal, but this is tedious and error prone, and that's where our today's hero comes in.

Embind. I will not write much about it here, because the official documentation is quite comprehensive to get hands on. Just one remark from the official docs to make this discussion complete. Binding class methods and properties with EMSCRIPTEN_BINDINGS(my_class_example) {class_<MyClass>("MyClass") /* ... */} allows to use it from JavaScript in a "normal" way without worrying about how this works at low level.

var instance = new Module.MyClass(10, "hello");
instance.incrementX();
instance.x; // 11
instance.x = 20; // 20
Module.MyClass.getStringFromInstance(instance); // "hello"
instance.delete();

Let's now look at the example from some real-world project...

Example: GUI for a motion planning library

There is an open-source project which is of personal interest for me -- a robotic motion planning library which is called Ruckig. It is a relatively small C++17 tool which does one thing and does it well -- it plans kinematically-optimal multi-degrees-of-freedom trajectories for robotics controllers. Doesn't matter what it really means. It is a software library that is supposed to be a part of another software tools or libraries. It has Python bindings (of course), and can be used from a Jupyter notebook. Well, as I found recently, it now has WebAssembly bindings too to provide a simple web GUI.

For it is a good chance to peek inside and learn something by example...

Install it for local development and peek inside

Let us quickly look inside Ruckig project. Jump into the GitHub repository of the community version (MIT license) and clone it.

git clone https://github.com/pantor/ruckig

We don't have to build it with CMake, so don't worry about right building tools. It can just live in a Windows folder for now if it is your platform.

If we go to src/ruckig, we will find a file wasm.cpp which contains all the Embind bindings for the web GUI, which allows to seamlessly bind input/output into underlying C++ library.

The web GUI itself is in doc/web-gui. To build it, we need to compile the C++ library to the ruckig.wasm binary first. This can be done by running doc/web-gui/make_wasm.sh in Bash, or if you are in Windows PowerShell, just run the following command in the terminal or put it in a *.bat file (this implies that Emscipten SDK is installed and activated and the environmental variables are already sources into current shell)

emcc src/ruckig/wasm.cpp src/ruckig/brake.cpp src/ruckig/position_first_step1.cpp src/ruckig/position_first_step2.cpp src/ruckig/position_second_step1.cpp src/ruckig/position_second_step2.cpp src/ruckig/position_third_step1.cpp src/ruckig/position_third_step2.cpp src/ruckig/velocity_second_step1.cpp src/ruckig/velocity_second_step2.cpp src/ruckig/velocity_third_step1.cpp src/ruckig/velocity_third_step2.cpp -Iinclude -Ithird_party -std=c++17 -lembind -Os -s MODULARIZE -s EXPORT_ES6 -s EXPORT_NAME='RuckigModule' -s ENVIRONMENT='web' -s EXPORTED_RUNTIME_METHODS=ccall,cwrap -o doc/web-gui/src/ruckig.js

This gives us two files ruckig.wasm binary, and ruckig.js glue code to load this binary into a browser session and interface with a Plotly.js React component, which shows fancy plots on the web page.

If you have resent version of Node.js, you can quickly build you local copy of web GUI by running the following commands in the root directory of the project.

npm install
npm run start

This will serve the page at localhost:1234. Now, make a cup of coffee (if it is still morning) and just look inside the doc/web-gui/ at index.html and gui.js. That's it.

C/C++ code in React using WebAssembly

Igor Proskurin — Wed, 13 Sep 2023 04:54:14 +0000

I started looking into WebAssembly (WASM) recently having a small project in mind. The project is to make a web interface for an open-source numeric C++17 library. I was thinking about a web application using a popular framework such as React. So here we go. This post is about my first experience with using C code compiled to WebAssembly in React.

While it was relatively easy to compile and call C-code from JavaScript which I described in the first and second posts, making it work with React required much more time and patience. I did my homework, and I knew about difficulty with loading WASM modules. I read about solutions based on wasm-loader withreact-app-rewired as discussed here. And I tried fetch WASM directly as described in MDN Docs. But each time the result was the same -- my WASM module refused to load at runtime complaining about "incorrect MIME types" or something like that.

Finally, the only solution that really worked for me was to compile C code in Emscripten with -sSINGLE_FILE=1. What it does? It embeds WebAssembly binary directly into JavaScript glue code, which is then used to call byte code at runtime. This solved my problems with loading WASM modules.

Here is what I did step by step...

Setting up a React App

If you are new to React (like myself), there is a good introduction at MDN Docs. I used Node.js v16.20.0, which is bundled with Emscripten compiler. Just type in the terminal (I used PowerShell this time)

$npx create-react-app  react-wasm
$cd react-wasm
$npm start

And we have a demo React project in the directory react-wasm up and running at localhost:3000. We will need to install some more stuff for our demo, but it can be done later. There is no rush...

Preparing a toy C library

I am going a prepare a toy C library. One function will be only for side effects, and another one will be a "numeric algorithm" -- it will take data from an input buffer, transform it, and put it into an output buffer. The input buffer will be filled in from JavaScript and the output data should be rendered by some React component (I will just use react-plotly.js to make some visuals). So here is our C file:

// hello_react.c

#include <assert.h>
#include <stdio.h>

void hello_react() {
    printf("Hello, React!\n");
}

void process_data(double* input, double* output, int size) {
    int i;

    assert(size > 0 && "size must be positive");
    assert(input && output && "must be valid pointers");

    for (i = 0; i < size; i++) {
        output[i] = input[i] * input[i];
    }
}

If you like to compile this file as C++, just wrap the function into extern "C" {} to prevent function names being mangled (in a WASM binary our functions will be translated into symbols _hello_react and _process_data). I saved this file as react-wasm/src/hello_react.c into src folder of the React project.

The next step is to compile this file into WASM binary and JavaScript glue code to interface it with React. I use Emscripten compiler that wraps around LLVM. There are two compiler options that make our life easier. One is -sMODULARIZE that helps to run WASM code in Node.js. Another one is -sSINGLE_FILE=1.

As I mentioned above, without -sSINGLE_FILE=1 the emcc compiler produces a separate *.wasm file that has to be loaded into browser at runtime. In my case (I mostly followed a method described here with some variations), whenever I used a separate file, it refused to load, despite the fact that I could build a package with npm. According to Emscripten FAQ: "another option than a local webserver is to bundle everything into a single file, using -sSINGLE_FILE (as then no XHRs will be made to file:// URLs)." This worked for me.

Okay, the final command to compile out toy C "library" with Emscripten looks like this.

$emcc hello_react.c -o hello_react.js -sMODULARIZE -sSINGLE_FILE=1 -sEXPORTED_FUNCTIONS=_hello_react,_process_data,_malloc,_free,getValue -sEXPORTED_RUNTIME_METHODS=ccall

Now, we have hello_react.js that contains JavaScript glue code and embedded WASM code (and we don't have a separate hello_react.wasm). We also asked the compiler to export some functions for us including _hello_react and _process_data.

Interfacing with React components

Now comes the fun stuff. How can we integrate our compiled file hello_react.js into a React component? Let's move step by step...

To call a JavaScript module with WASM code, I will mostly follow the method for interoperability with Node.js from Emscripten Docs. The basics idea is to to call require('./hello_wasm.js') which returns a promise.

var factory = require('./hello_react.js');

factory().then((instance) => {
  instance._hello_react(); // direct calling
  instance.ccall("hello_react", null, null, null);
  // more code...
});

Here, we can call our C function directly via the exported symbol _hello_react or using a runtime method ccall.

Now index.js inside my src folder looks like this.

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';

var factory = require('./hello_react.js');

factory().then((instance) => {
  instance._hello_react(); // direct calling
  instance.ccall("hello_react", null, null, null);
});

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

At this point, we can run our project with npm start... And see that it doesn't work.

The first problem is specific to webpack, and there is a standard workaround, which is called react-app-rewired. So our next step is to install this package.

$npm install react-app-rewired

And set up config-overrides.js in the root directory of the project with the following content.

module.exports = function override(config, env) {
  config.resolve.fallback = {
    fs: false
  };
  return config;
};

After that I just modify the script section of the package.json to call react-app-rewired at startup.

"scripts": {
    "start": "react-app-rewired start",
    "build": "react-app-rewired build",
    "test": "react-app-rewired test",
    "eject": "react-app-rewired eject"
  },

Next step is npm install path so we can silence the following.

Module not found: Error: Can't resolve 'path' in 'C:\Users\Igor\Devel\react-wasm\src'

This almost works. The only remaining thing is the annoying eslint complaints, which I silenced using a temporary solution simply by adding the following lines on top of hello_react.js.

/* eslint-disable no-undef */
/* eslint-disable  no-restricted-globals */
/* eslint-disable import/no-amd */

Now, we open the console, and see that our function has been called.

Okay, this part works. We can even built package with npm run build at this point. Now let's go a little bit further and try to connect WASM code with a React component.

Mocking interface between C code and a React component

I will use Plotly.js as a simple graphical react component.

$npm install plotly-react.js plotly.js

Since I am using low-level C code here, I will need to make an input buffer using _malloc to pass data to the WASM module. We already exported it when compiled our C file with emcc. And I will use a separate output buffer to get data out. Let me skip some little steps here. More details can be found in my previous post.

Out index.js now looks like this.

import React from 'react';
import ReactDOM from 'react-dom/client';
import './index.css';
import App from './App';

var factory = require('./hello_react.js');

factory().then((instance) => {
  const inputArr = new Float64Array([0, 1, 2, 3, 5]);
  const inputBuff = instance._malloc(inputArr.length * inputArr.BYTES_PER_ELEMENT);
  instance.HEAPF64.set(inputArr, inputBuff / inputArr.BYTES_PER_ELEMENT);

  let outputArr = new Float64Array(inputArr.length);
  const outputBuff = instance._malloc(inputArr.length * inputArr.BYTES_PER_ELEMENT);

  instance.ccall('process_data', 'number', ['number', 'number', 'number'], [inputBuff, outputBuff, inputArr.length]);

  for (let i = 0; i < outputArr.length; i++) {
      outputArr[i] = instance.getValue(outputBuff + i * outputArr.BYTES_PER_ELEMENT, 'double');
  }

  console.log(inputArr);
  console.log(outputArr);

  instance._free(outputBuff);
  instance._free(inputBuff);

  const root = ReactDOM.createRoot(document.getElementById('root'));

  root.render(
    <React.StrictMode>
      <App />
    </React.StrictMode>
  );

});

To get data out of the output buffer, I used a low-level operation getValue (there is no HEAPF64.get in the API).

for (let i = 0; i < outputArr.length; i++) {
      outputArr[i] = instance.getValue(outputBuff + i * outputArr.BYTES_PER_ELEMENT, 'double');
  }

Let's check console logs and find correct input and output array values.

Let's now use this data somewhere...

Let's visualize what we get

We can add a simple script into src folder to plot input and output using a Plotly.js component <Plot /> (sprinkle it with some CSS if you like).

// MyPlot.js
import React from 'react';
import Plot from 'react-plotly.js';
import './MyPlot.css'

function MyPlot(props) {

    const xs = props.xs;
    const ys = props.ys;

    const plots = [{
        x: xs, 
        y: ys, 
        type: 'scatter', 
        mode: 'lines+markers', 
        marker: {color: 'red'}
    }];

    return (
        <div className='MyPlot'>
            <Plot
              data={ plots }
              layout={ {width: 640, height: 480, title: 'Plotly React'} }
            />
        </div>
    );
}

export default MyPlot;

Now the component is ready to use from index.js. Just add import MyPlot from './MyPlot' and update the rendering

root.render(
    <React.StrictMode>
      <App />
      <MyPlot xs={inputArr} ys={outputArr} />
    </React.StrictMode>
  );

Voila!

Playing with low-level memory allocation in WebAssembly

Igor Proskurin — Wed, 06 Sep 2023 03:58:19 +0000

I wrote a blog post about my first experience with WebAssembly (WASM) recently. And in that post, I touched a little bit how to set up an SDK for writing code in C/C++, and how to compile a simple C++ function that can takes couple of numeric values from JavaScript, run WASM binary in a browser, and return a value.

For those who just jumped in, WebAssembly is cool cross-platform binary format, assembly language, and a Virtual Machine to run this binary in a browser. What can it do? Well, it can mine crypto currency silently in background while you go through your favorite webpages. And guess who pays for the electricity?

Well, besides crypto-currency abuse, it is an interesting technology to run heavy stuff client-side with reasonable performance.

Where to start

In this post, I am playing around with Emscipten. It is a WASM compiler which wraps around clang to compile C/C++ source code in a binary .wasm format. It also provides some glue-code API to embed this WASM binary into JavaScript. Just look into MDN Docs and Emscripten SDK to get started.

Managing memory with Emscripten

Before, diving into high-level Emscripten stuff such as Embind, I decided to look into its low-level memory model.

Here is a toy problem. We have a C-function that takes an array of double precision values, do something with them and return a number. It may look as simple this.

// malloc_testing.c

#include <assert.h>
#include <math.h>
#include <stdio.h>

double vector_norm(double* p, int n) {
    int i;
    double norm2 = 0;

    assert(n > 0 && "number of elements must be positive");
    assert(p && "must be a valid pointer");
    printf("received: n = %d\n", n);

    for (i = 0; i < n; i++) {
        printf("processed: p[%d] = %.3f\n", i, p[i]);
        norm2 += p[i] * p[i];
    }
    return sqrt(norm2);
}

In the code, I sprinkled some asserts and old-fashioned print-outs for convenience. Don't forget to wrap it in extern "C" {} if you are going to treat as C++ code.

We already know that this function can be called from JavaScript using ccall() or cwrap() methods, but how can we pass an array from JavaScript to our C-code?

Let us compile this function into a binary using Emscripten emcc compiler.

$emcc malloc_testing.c -o malloc_testing.js -O0 -sASSERTIONS=2 -sEXPORTED_FUNCTIONS=_vector_norm,_malloc,_free,setValue -sEXPORTED_RUNTIME_METHODS=cwrap,ccall

Here, I tell the compiler to keep the assertions by setting low optimization level -O0, and export some useful stuff like _malloc, _free, and setValue, and our C-function of course _vector_norm (note the leading underscore).

Now we have a couple of files: malloc_testing.wasm that contains a binary, and malloc_testing.js which is JavaScript glue code that allows us to use it from a web page. You can also run in Node.js, but in this case it should be compiled with -sMODULARIZE.

Allocating memory from JavaScript

How does memory model of the WASM VM look like? Well, for C/C++ code it look pretty normal: code, heap, stack. We can allocate stuff on the heap and pass pointers around. Luckily for us, we also asked emcc to export memory allocation, _malloc, in to the JavaScript glue code, so now we can allocate memory on the heap in WASM from JavaScript.

In theory, the whole process looks easy: allocate memory on the heap and get pointer into JavaScript code, write something into this memory, and pass this pointer to the C-function. Something like that:

Let's try it. I will use a simple web page set up to run our C-function inside the browser by pressing a button.

<!DOCTYPE html>
<html lang="en">
<body>

<button id="mybutton">Run</button>

<script>
    document.getElementById("mybutton").addEventListener("click", ()=>{

        const vectorNorm = Module.cwrap(
                               'vector_norm', // no underscore
                                'number',  // return type 
                                ['number', 'number']); // param types;

        const myTypedArray = new Float64Array([0, 1, 2, 3, 5]);

        // allocate empty buffer
        let buf = Module._malloc(myTypedArray.length * myTypedArray.BYTES_PER_ELEMENT);

        // fill  this buffer with our stuff
        Module.HEAPF64.set(myTypedArray, buf / myTypedArray.BYTES_PER_ELEMENT);

        // call our function and pass pointer to buffer
        const result = vectorNorm(buf, myTypedeArray.length);

        console.log(`result = ${result}`);

        Module._free(buf);  // no leaks!
    });
</script>

<script src="malloc_testing.js"></script>

</body>

Here, I first create a JavaScript typed array with float64 continuous view of memory.

After that, I create an empty buffer on the heap inside WASM memory by calling to _malloc that we exported when we compiled our C-file. It returns a pointer buf to the allocated segment of memory, which in JavaScript code is treated simply as a number (very "safe", eh?).

Next step is to fill allocated memory with something. I use Module.HEAPF64.set(myTypedArray, buf / myTypedArray.BYTES_PER_ELEMENT) that takes two arguments: my array, and a pointer to the buffer. Note the alignment! The pointer must count by 8-bytes. It actually took me more than an hour to figure it out since Empscipten API docs are quite, hm, emscryptic on this point. Thanks to ChatGPT and this post.

To see how it works, we can replace the call to HEAPF64.set by manual allocation. I came up with something like this (don't do it anywhere near production!):

function setMemoryManually(myArray, ptr) {
    for (const x of myArray) {
        Module.setValue(ptr, x, 'double');
        ptr += myArray.BYTES_PER_ELEMENT;
    }
}

It looks ugly, but works. Low-level function Module.setValue(ptr, value, 'double') can be used to manually set a value at the address pointed by ptr. In this case, no tricks. The pointer is incremented by BYTES_PER_ELEMENT = 8 for double. So now I can write something like setMemoryManually(myTypedArray, buf) in my JavaScript code, and it will fill the buffer with the content of myTypedArray.

When all memory is set, we can call our C-function from JavaScript. I prefer to wrap it up first.

const vectorNorm = Module.cwrap('vector_norm', // no underscore
                                'number',  // return type 
                                ['number', 'number']); // param types;

We tell cwrap that we return a number, and we pass a couple of number values. Yes, the pointer to the buffer of the allocated memory is passed as a number (looks very "safe" and "portable", eh?). So we can just call vectorNorm from our script.

const result = vectorNorm(buf, myTypedArray.length);

Last step. Open a browser, serve our http-web page from a local host (I just run python -m http.server)

http://localhost:8000/wasm_testing/malloc_testing.html

hard reload, press Run, and here we go

received: n = 5
p[0] = 0.000
p[1] = 1.000
p[2] = 2.000
p[3] = 3.000
p[4] = 5.000
result = 6.244997998398398

In summary...

Playing with low-level stuff is fun, but I won't use it anywhere in productionable code. Well, at least without considerable experience and understanding of the Emscripten code base.

My first take on WebAssembly

Igor Proskurin — Mon, 04 Sep 2023 03:31:03 +0000

Here we go, I decided to try WebAssembly having a project in mind, but before dedicating myself and take on coding, there is always fun of fooling around with some code.

If you are new to WebAssembly, the first place to go after Wikipedia is probably MDN Web Docs that gives a decent introductory background. It explains that WebAssembly is binary format and the corresponding assembly language that runs in a Virtual Machine built into all modern browsers. It sounds like a blasphemy if you are an acolyte of Unix Philosophy, but otherwise it is a cool client-side portable technology to deal with high-performance numeric computations (no, no, I am not talking about crypto mining).

So where should we start?

First comes a compiler

In order to use WebAssembly with our shiny cool numeric C/C++ libraries (you are not going to manually write assembly, aren't you?), we need a compiler that takes C/C++ source as an input and generates a *.wasm binary file along with some JavaScript glue code, which is needed to call binary code from a web-page or Node.js. Well, MDN recommends to use Emscipten, which wraps around LLVM clang compiler, and I am not in a position to make a reasonable argument about other options...

I will skip the details of how to install Emscripten SDK. It is pretty easy. Just note that the most reasonable and sane way to use emcc compiler is, probably, from bash. But I decided to give it a try from PowerShell first without additional abstractions like WSL, and it worked... Nice surprise.

Let's compile something

Well, let me skip a hello world example, and start with some basic questions one needs to figure out before starting a project.

How can I interface my C/C++ code with JavaScript? At minimum, I need to call some functions. It would be nice to have a full support of classes, threads, etc -- but maybe later, okay?
How can I pass anything from JavaScript to C/C++. Passing a couple of doubles would be nice, but I also need to pass Float64 arrays and aggregate data like struct.
How would my C/C++ library functions return anything meaningful rather than a single numeric value?

Let's move one step after another and take time to look around...

Calling C-functions using `ccall()`

Let us prepare a very basic "numeric library".

// ccall_testing.cpp

#include <cmath>
#include <iostream>

#include <emscripten/emscripten.h>

extern "C" {

EMSCRIPTEN_KEEPALIVE double my_norm(double x, double y) {
    std::cout << "my_norm is called\n";
    return std::sqrt(x * x + y * y);
}

}

And yes, ccall() is to call C-functions, so here is extern "C" to deal with C++ name mangling. We also need EMSCRIPTEN_KEEPALIVE to prevent this code to be optimized out as dead code.

Now, don't forget to source all the environmental variables from your shell of choice. There is a collection of shell scripts for doing it in your Emscripten SDK source directory. In PowerShell, I just run ./emcmdprompt.bat.

Then compile our source file using emcc:

$emcc ccall_testing.cpp -o ccall_testing.js -sEXPORTED_RUNTIME_METHODS=ccall

We have two files. The first is WebAssembly binary ccall_testing.wasm and the second is JavaScript glue code ccall_testing.js. It is possible to use html as the compiler's target, and it will generate a web-page, but I will stick to *.js to remain in control.

It is time to call our library function from a web page. Let's come up with something very basic:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>My WASM experiments</title>
</head>
<body>

<button id="mybutton">Run</button>

<script>
    document.getElementById("mybutton").addEventListener("click", ()=>{
        const result = Module.ccall("my_norm", // yes, that's our function
                            "number",               // return type
                           ["number", "number"],    // argument types
                           [3.0, 4.0]           // yeah, Pythagorean triple
                       );

        console.log(`result = ${result}`);
    });
</script>

<script src="ccall_testing.js" type="text/javascript" async></script>

</body>
</html>

Save this as ccall_testing.html and then run in the browther. Does not work? There is additional step. In order to load *.wasm blob, we can serve the page from a simple http-server:

$python -m http.server

which will open a connection at localhost:8000. Now just open html-file in the directory of your choice:

http://localhost:8000/wasm_testing/ccall_testing.html

Press Run, open a console Ctrl-Shift-I and Voila! (don't forget Ctrl+R to reload cache):

my_norm is called   ccall_testing.js:1559:16
result = 5

Prefer wraps instead of calls?

No problem! It is possible to wrap C-function directly into JavaScript function using cwrap().

In this case, we don't need EMSCRIPTEN_KEEPALIVE any more because we will tell the compiler to export this function anyway so our cpp-file becomes a bit cleaner

// cwrap_testing.cpp

#include <cmath>
#include <iostream>

#include <emscripten/emscripten.h>

extern "C" {

double my_norm(double x, double y) {
    std::cout << "my_norm is called\n";
    return std::sqrt(x * x + y * y);
}

}

Call the compiler and add -sEXPORTED_FUNCTIONS=_my_norm with an underscore in front of the function name (that's an assembly symbol, like _start)

$emcc cwrap_testing.cpp -o cwrap_testing.js -sEXPORTED_FUNCTIONS=_my_norm -sEXPORTED_RUNTIME_METHODS=cwrap

Our html file also becomes slightly different. Here, I introduce a new JavaScript function myNorm that wraps around the C-library function call

<button id="mybutton">Run</button>

<script>
    document.getElementById("mybutton").addEventListener("click", ()=>{
        const myNorm = Module.cwrap("my_norm", // no underscore
                                    'number',  // return type 
                                    ['number', 'number']); // param types;
        const result = myNorm(3.0, 4.0);
        console.log(`result = ${result}`);
    });
</script>

<script src="cwrap_testing.js" type="text/javascript" async></script>

The result is the same as for ccall(). That's nice. But how can we pass something more meaningful?

But I need to pass an array of `Float64`...

The naive question would be: can we use 'array' instead of 'number' in the function call? So our code would look like: Module.ccall("my_norm", "number", "array", [3.0, 4.0])?

The answer is "not so simple"... The array type here really means something like "raw byte buffer".

According to the API documentation: " 'array' [is] for JavaScript arrays and typed arrays, containing 8-bit integer data - that is, the data is written into a C array of 8-bit integers".

So if we need to pass an array of doubles, it is either a manual allocation and passing a pointer (as a 'number') or Embind.

Yeah, Embind is cool! Let's come back to that...

DEV Community: Igor Proskurin

Using GNU toolchain for Windows kernel-mode drivers

Driver Hello World

Using GNU ld for linking

Loading and unloading

Summary

Generics in Rust: murky waters of implementing foreign traits on foreign types

We can't do it, or can we?

How can nalgebra do it?

We can do what we can't

Summary

Generics in Rust: visualizing Bezier curves in a Jupyter notebook -- Part 3

First comes REPL - evxvr

Adding external dependencies

Plotting with Plotters

Summary

Generics in Rust: little library for Bezier curves -- Part 2

First steps

Implementing eval-method

Implementing diff and integ methods

Generic product of two polynomials

Summary

Experimenting with generics in Rust: little library for Bezier curves - part 1

Tiny generic numeric library: requirements

Generic Bezier curves: design considerations

Next steps...

Generic constant expressions: a future bright side of nightly Rust

Generic constant expression parameters

Constant expression generic parameters in functions

Constant expression generic parameters in types

What does not work...

Summary

WebAssembly: Building GUI for C++ libraries with Embind

What should I use it for?

A little bit about Embind

Example: GUI for a motion planning library

Install it for local development and peek inside

C/C++ code in React using WebAssembly

Setting up a React App

Preparing a toy C library

Interfacing with React components

Mocking interface between C code and a React component

Let's visualize what we get

Playing with low-level memory allocation in WebAssembly

Where to start

Managing memory with Emscripten

Allocating memory from JavaScript

In summary...

My first take on WebAssembly

First comes a compiler

Let's compile something

Calling C-functions using ccall()

Prefer wraps instead of calls?

But I need to pass an array of Float64...

How can `nalgebra` do it?

Calling C-functions using `ccall()`

But I need to pass an array of `Float64`...