How resource constrained? How about an HP-16C (Wikipedia), a programmable programmer’s calculator from over 30 years earlier? ~200 bytes total of program and storage should be enough.

I’m not going to pretend I’m going to be good at teaching you how to use these HP calculators. There are tutorials online all over that will do a far better job at explaining them. If you don’t have an HP-16C, you can use JRPN 16C as an in-browser emulator. It can directly import the listing below for your convenience.

Example

Computing the hash function on an empty string, Ascon-Hash256(""), which should be 0b 3b e5 85 0f 2f 6b 98 ca f2 9f 8f de a8 9b 64 a1 fa 70 aa 24 9b 8f 83 9b d5 3b aa 30 4d 92 b2.

First, pad the message with one 01 byte and as much zeros as needed to get to a multiple of 8. Bytes are read/written in little-endian, so the padded message is a single block 0x0000000000000001. Then do the following:

• Enter the program (see end of post)
• Set mode: [HEX] 0 [f] [WSIZE] [f] [UNSGN] (set hexadecimal, 64-bit, unsigned)
• Initial value: [f] [CLEAR REG] 80100cc0002 [STO] [0]
• Initialization: C [GSB] [0] to apply the 12-round Ascon-p[12] permutation. You should get 9b1e5494e934d681, which is S0
• XOR message: 1 [f] [XOR] [STO] [0], you should get 9b1e5494e934d680
• Process message: C [GSB] [0] to apply again
• Read hash: you should get 986b2f0f85e53b0b. Read bytes in little-endian, so the first 8 bytes are 0b 3b e5 85 0f 2f 6b 98
• Iterate once more and read further bytes of hash: C [GSB] [0], you should get 649ba8de8f9ff2ca, hence ca f2 9f 8f de a8 9b 64
• Repeat until all 64 bytes are produced

(Note: Only R0 is directly used to XOR the input onto and form the hash. It is, as a convenience, recalled after every [GSB] [0]. Other registers participate in the round function but the bytes are not directly used for input and output.)

Program listing

This program isn’t specifically optimized — it is just a straightforward translation of one of the C reference implementations. It takes 140 lines of program space. On a real 16C it takes about 20 seconds per round, so Ascon-p[8] (8 rounds) takes ~2.5min, and Ascon-p[12] (12 rounds) takes ~4min.

(In JRPN 16C compatible format, so you can load it in directly via (menu) > File > Import Program > Import from Clipboard. Set (menu) > Settings > Long Numbers to Grow LCD and (menu) > Settings > System Settings > ms/Program Instruction to 0 for extra convenience.)

# Ascon round function
#
# Usage:
# Assumed Mode: [HEX] 0 [f] [WSIZE] [f] [UNSGN] (hexadecimal, 64-bit, unsigned)
#
# Modifies state S0 through S4 stored in R0 through R4
# Uses R5, R6 as scratch
#
#    Single round: <round constant> [GSB] [A]
#            e.g.: b4 [GSB] [A]
#
# Up to 12 rounds: <num rounds> [GSB] [0]
#            e.g.: 8 [GSB] [0]    for Ascon-p[8]
#            e.g.: C [GSB] [0]    for Ascon-p[12]
#
# 2026-01-18: Updated the multi-round subroutine to free up I register. Not
#             enough for a key, but you could store the IV there.
# 2026-02-23: Subroutine 0 performs RCL 0 at end for convenience
#             Minor peephole optimization near the start of subroutine A

   000 {          }
# Single round
   001 { 43 22  A } g LBL A

# s2 ^= s1 ^ c
   002 {    45  1 } RCL 1
   003 {    45  2 } RCL 2
   004 {    42 10 } f XOR
   005 {    42 10 } f XOR
   006 {    44  2 } STO 2

# s0 ^= s4
   007 {    45  4 } RCL 4
   008 {    45  0 } RCL 0
   009 {    42 10 } f XOR
   010 {    44  0 } STO 0

# s4 ^= s3
   011 {    45  3 } RCL 3
   012 {    45  4 } RCL 4
   013 {    42 10 } f XOR
   014 {    44  4 } STO 4

# tmp = ~s4 & s0
# (s4 already conveniently on TOS)
   015 {    42 30 } f NOT
   016 {    45  0 } RCL 0
   017 {    42 20 } f AND
   018 {    44  5 } STO 5

# s0 ^= ~s1 & s2
   019 {    45  1 } RCL 1
   020 {    42 30 } f NOT
   021 {    45  2 } RCL 2
   022 {    42 20 } f AND
   023 {    45  0 } RCL 0
   024 {    42 10 } f XOR
   025 {    44  0 } STO 0

# s2 ^= ~s3 & s4
   026 {    45  3 } RCL 3
   027 {    42 30 } f NOT
   028 {    45  4 } RCL 4
   029 {    42 20 } f AND
   030 {    45  2 } RCL 2
   031 {    42 10 } f XOR
   032 {    44  2 } STO 2

# s4 ^= ~s0 & s1
   033 {    45  0 } RCL 0
   034 {    42 30 } f NOT
   035 {    45  1 } RCL 1
   036 {    42 20 } f AND
   037 {    45  4 } RCL 4
   038 {    42 10 } f XOR
   039 {    44  4 } STO 4

# s1 ^= ~s2 & s3
   040 {    45  2 } RCL 2
   041 {    42 30 } f NOT
   042 {    45  3 } RCL 3
   043 {    42 20 } f AND
   044 {    45  1 } RCL 1
   045 {    42 10 } f XOR
   046 {    44  1 } STO 1

# s3 ^= tmp
   047 {    45  5 } RCL 5
   048 {    45  3 } RCL 3
   049 {    42 10 } f XOR
   050 {    44  3 } STO 3

# s1 ^= s0
   051 {    45  0 } RCL 0
   052 {    45  1 } RCL 1
   053 {    42 10 } f XOR
   054 {    44  1 } STO 1

# s3 ^= s2
   055 {    45  2 } RCL 2
   056 {    45  3 } RCL 3
   057 {    42 10 } f XOR
   058 {    44  3 } STO 3

# s0 ^= s4
   059 {    45  4 } RCL 4
   060 {    45  0 } RCL 0
   061 {    42 10 } f XOR
   062 {    44  0 } STO 0

# s0 = s0 ^ (s0 ror 19) ^ (s0 ror 28)
   063 {    45  0 } RCL 0
   064 {       36 } ENTER
   065 {       36 } ENTER
   066 {       36 } ENTER
   067 {        9 } 9
   068 {    42  F } f RRn
   069 {    42 10 } f XOR
   070 {        1 } 1
   071 {        3 } 3
   072 {    42  F } f RRn
   073 {    42 10 } f XOR
   074 {    44  0 } STO 0

# s1 = s1 ^ (s1 ror 39) ^ (s1 ror 61)
   075 {    45  1 } RCL 1
   076 {       36 } ENTER
   077 {       36 } ENTER
   078 {       36 } ENTER
   079 {        1 } 1
   080 {        6 } 6
   081 {    42  F } f RRn
   082 {    42 10 } f XOR
   083 {        2 } 2
   084 {        7 } 7
   085 {    42  F } f RRn
   086 {    42 10 } f XOR
   087 {    44  1 } STO 1

# s2 = s2 ^ (s2 ror 1) ^ (s2 ror 6)
   088 {    45  2 } RCL 2
   089 {       36 } ENTER
   090 {       36 } ENTER
   091 {       36 } ENTER
   092 {        5 } 5
   093 {    42  F } f RRn
   094 {    42 10 } f XOR
   095 {    42  D } f RR
   096 {    42 10 } f XOR
   097 {    44  2 } STO 2

# s3 = s3 ^ (s3 ror 10) ^ (s3 ror 17)
   098 {    45  3 } RCL 3
   099 {       36 } ENTER
   100 {       36 } ENTER
   101 {       36 } ENTER
   102 {        7 } 7
   103 {    42  F } f RRn
   104 {    42 10 } f XOR
   105 {        A } A
   106 {    42  F } f RRn
   107 {    42 10 } f XOR
   108 {    44  3 } STO 3

# s4 = s4 ^ (s4 ror 7) ^ (s4 ror 41)
   109 {    45  4 } RCL 4
   110 {       36 } ENTER
   111 {       36 } ENTER
   112 {       36 } ENTER
   113 {        2 } 2
   114 {        2 } 2
   115 {    42  F } f RRn
   116 {    42 10 } f XOR
   117 {        7 } 7
   118 {    42  F } f RRn
   119 {    42 10 } f XOR
   120 {    44  4 } STO 4

# s2 = ~s2
   121 {    45  2 } RCL 2
   122 {    42 30 } f NOT
   123 {    44  2 } STO 2

   124 {    43 21 } g RTN

# Multiple rounds
   125 { 43 22  0 } g LBL 0
   126 {        4 } 4
   127 {       40 } +
   128 {        F } F
   129 {       20 } *
   130 { 43 22  B } g LBL B
   131 {    44  6 } STO 6
   132 {    21  A } GSB A
   133 {    45  6 } RCL 6
   134 {        4 } 4
   135 {        B } B
   136 {    43 49 } g x==y
   137 {    22  C } GTO C
   138 {       33 } Rv
   139 {        F } F
   140 {       30 } -
   141 {    22  B } GTO B
   142 { 43 22  C } g LBL C
   143 {    45  0 } RCL 0
   144 {    43 21 } g RTN

Check it out if you want a way to serve the contents from a git repo over HTTP(S) on the public Internet.

The backend server on grebedoc.dev is called git-pages. I’ll probably use the two names interchangably for the rest of this article.

(However, I will use “grebedoc.dev” to specifically refer to the domain itself, and use grebedoc.dev to refer to the service.)

Zero downtime migration

I think I’ve managed to do a zero-downtime migration from Netlify. This is what I did:

First, I moved everything to the pages branch. This is just easier.

Then, I set up the “method 1” DNS record:

_git-pages-repository.dram.page.  600  IN  TXT  (
    "https://github.com/dramforever/dram.page.git" )

Then, I triggered an initial clone using the PUT method.

$ curl -v -X PUT -H 'Host: dram.page' \
    'https://grebedoc.dev' \
    --data 'https://github.com/dramforever/dram.page.git'

This has two effects:

• It asks git-pages to start serving files for Host: dram.page
• It registers dram.page as a known domain to git-pages, allowing it to immediately start receiving HTTPS requests. This lets me to completely avoid sending anything over unencrypted HTTP, including the webhook.

Now I can see if it’s serving my pages correctly:

$ curl -v -H 'Host: dram.page' 'https://grebedoc.dev'

For me, that looked good, so I’m ready to do the switch, changing the actual DNS record to make my site point to the grebedoc.dev server:

dram.page.  600  IN  ALIAS  grebedoc.dev

… well, ALIAS is not a real DNS record. The effect is that the authoritative DNS server looks up the IPv4 and IPv6 address of the domain grebedoc.dev and serves them as A and AAAA records of dram.page. Fortunately my authoritative DNS service has this feature.

And that’s it, I’m serving the latest site on grebedoc.dev.

As for auto-updating, the webhook part works normally.

What’s wrong with Netlify?

Nothing, really, but since I use zero complex features and just serve what’s in the git repo, this is just simpler.

One problem with the slide rule I carry daily (a Faber-Castelle 62/82) is that it’s rather small, about half a foot (around 15 centimeters) in length. (Presumably, the “6” in its name refers to its length of 6 inches.) This means there are fewer markings on it, and the precision of the numbers read from it is limited. I can only, for the most part, get 2 significant digits out of it.

Today I learned about a trick published over 60 years ago that allows me to pretty consistently get to 3 significant digits on the same hardware, at the cost of some more manipulations. To me, it felt like a software upgrade to my slide rule. How does it work? Let’s find out.

The method

Here’s a simplified representation of the two conventional scales C and D. The top scale here is C, and the bottom is D. They both go from 1 to 10, and the horizontal lengths are proportional to the logarithm of the numeric values.

For convenience, we’ll refer to the two scales as “top scale” and “bottom scale”.

Let’s say we want to read the position of the hairline on the bottom scale, shown here as a long red line:

We can see that it’s between 3.7 and 3.8, but it would be difficult to ascertain the next digit.

Step 1: Line up 10 on the top scale with 9 on the bottom scale:

Step 2: Go back to the hairline, and find a nearby marking on the top scale that is close to the hairline:

Step 2: Move the top scale so that the found marking lines up with the hairline:

Let’s zoom in on the hairline:

Step 3: Starting at the hairline position, going in the positive direction.

• On the bottom scale, count markings after the hairline, starting at 1.
• On the top scale, count markings starting at the one at the hairline as 0.

Find the pair of markings that line up best and note the number. Here, marking number 3 lines up best, as marked by the magenta dot.

If you’re having trouble telling which line matches up, note how on the left of the correct line, the bottom markings deviate left, and similarly on the right side the bottom markings deviate right.

(This is exactly how you read a Vernier scale, by the way.)

Step 4: Whatever the number is, the hairline is that many tenths of a division past the previous marking.

For example, since the number of the line matching up is 3, and the hairline is between 3.7 and 3.8, we know the hairline is at 3.7 + 0.1 × (3/10) = 3.73.

That is, in fact, exactly the value I used to generate the position of this hairline.

How does this work?

Corresponding positions on the top and bottom scale preserve proportions. Therefore, when we line up 10 on the top scale with 9 on the bottom scale, the numbers on the top scale are 10/9 times the number on the bottom scale. This means that the distance between markings on the top scale must be 9/10 of the distance on the bottom scale. This turns our slide rule markings into a Vernier scale, and can be read similarly.

Of course, this makes a few approximating assumptions. Firstly, it assumes that the markings are locally linear. Secondly, it assumes that the adjusting step 2 does not affect distance proportions much. Therefore, the new significant digit provided by this method is an approximate value.

More details on usage

This method also won’t directly work if the two scales have different amount of increment per division. You may have to ignore some markings to make it work.

It also does not work directly with positions after 9. However, you can consider using a folded scale (CF and DF) to move the value closer to the middle of the slide rule. Some slide rules (such as my 62/82) have “overflow” areas before 1 and after 10 that may help.

You can also count backwards to the previous matching line, and extrapolate the answer, noting that 9 divisions on the bottom equals 10 divisions on the top. The original article even suggests trying other proportions.

References

The method described in this article was originally published in: Roger Wickenden, 1948, Utilizing the Vernier Principle for Precise Readings of Slide Rule Settings, doi:10.1119/1.1991139

Images in this article are based on work by Wrtlprnft, itself based on original image made by Benjamin Crowell. See the original file at: https://en.wikipedia.org/wiki/File:Slide_rule_example3.svg

License and source code

This article, including the images, are licensed under the Creative Commons Attribution-ShareAlike 4.0 International license. For more information on the license, see: https://creativecommons.org/licenses/by-sa/4.0/deed.en

The Markdown source to this page can be found at: https://github.com/dramforever/dram.page/blob/master/p/slide-rule-vernier/index.md

I hope what you were intending to implement is actually a programming language, not just something that got to the point of being accidentally Turing-complete. I wouldn’t judge either way though.

Side note: C features used in this article

I’m going to assume familiarity with the C language, but just to make easier for those less familiar with C, here are some explanations of less obvious constructs used in the code:

Infinite loop

for (;;) is an infinite loop.

Stack operations

We’re going to use arrays and pointers as stacks. The convention we’re going to use is:

uintptr_t stack_buf[STACK_SIZE];
uintptr_t *sp = stack_buf;

• The stack “grows up”, meaning that successive pushes go into higher indices.
• The stack pointer starts at the beginning of the underlying array.
• The stack pointer points to one element after the top element. So if the stack currently has 3 elements, then sp = stack_buf + 3.
• Using the semantics of C’s increment/decrement operators, *(sp++) = foo pushes foo on the stack, whereas bar = *(--sp) pops an element from the stack and assigns it to bar.

Function pointers

Later in the article we’re going to need to “store” functions as data. The way this is done is using a function pointer.

It’s possible to declare function pointers directly, but I’m going to use a typedef for the sake of your sanity:

typedef void (*codeptr)(void);

This means codeptr is now a type alias for the type “function pointer to a function that takes no arguments and returns void”.

(For historical reasons a parameter list of (void), not (), means “takes no arguments” in C.)

You can use this type in variables or members. The name of any function with the correct signature can be used as a value of type codeptr. To use a function pointer, just call it like any function.

void foo(void);
codeptr p = foo;
p(); // Calls foo

On most architectures a function pointer is represented by the address of the start of the code of a function.

Bytecode

A “bytecode” is one of the obvious popular choices. Each instruction has, say, one byte of opcode and several bytes of operands. Let’s also say we’re using a stack machine, because it’s also an obvious popular choice. A bytecode program might look something like this:

#define OP_EXIT 0
#define OP_PUSH 1
#define OP_ADD 2
#define OP_PRINT 3
// ... more opcodes

const uint8_t program[] = {
    OP_PUSH, 1, OP_PUSH, 1, OP_ADD, OP_PRINT, OP_EXIT,
};

And the interpreter would look something like this:

const uint8_t *ip = program;

uintptr_t stack_buf[STACK_SIZE];
uintptr_t *sp = stack_buf;

void interpreter(void) {
    for (;;) {
        switch (*ip) {
        case OP_PUSH:
            ip++;
            uintptr_t operand = *(ip++);
            *(sp++) = operand;
            break;

        case OP_ADD:
            ip++;
            uintptr_t b = *(--sp);
            uintptr_t a = *(--sp);
            *(sp++) = a + b;
            break;

        // ... more opcodes
        }
    }
}

Direct threaded code

The switch statement above would probably be compiled into a jump table by the compiler. If you don’t need the program to be serializable, one thing you can do is to simply store function pointers in an array, skipping the table altogether:

typedef void (*codeptr)(void);

void code_one(void);
// ... more functions

const codeptr program[] = {
    code_one, code_one, code_add, code_print, code_exit,
};

Instead of cases in a switch block, the individual opcodes are now individual functions

void code_one(void) {
    ip++;
    *(sp++) = 1;
}

void code_add(void) {
    ip++;
    uintptr_t b = *(--sp);
    uintptr_t a = *(--sp);
    *(sp++) = a + b;
}

// ...

And the interpreter would simply repeatedly call the current function pointer. For simplicity’s sake, we’ll keep the interpreter state in global variables (for now).

const codeptr *ip = program; // Changed!

uintptr_t stack_buf[STACK_SIZE];
uintptr_t *sp = stack_buf;

void interpreter(void) {
    for (;;)
        (*ip)();
}

Indirect threaded code

Instead of function pointers, the program can contain pointers to more complicated objects. An obvious example would be other programs, as an implementation of subroutines.

Since we want the handling of objects to remain uniform, each object would need a function pointer pointing to some code telling it what to do. Following it could be some payload. For simplicity, let’s say that the only possible payload is a subroutine.

To handle subroutine calls and returns, we’d also need to add a return stack pointer (rsp) to our interpreter state. We’ll see how to handle it later.

typedef void (*codeptr)(void);

struct object {
    codeptr code;
    const struct object *payload[];
};

const struct object *const *ip = ...; // Changed!

uintptr_t stack_buf[STACK_SIZE];
uintptr_t *sp = stack_buf;

// New: return stack
const struct object *const *rstack_buf[STACK_SIZE];
const struct object *const **rsp = rstack_buf;

Primitive objects can have code with no payload:

void code_add(void) {
    ip++;
    uintptr_t b = *(--sp);
    uintptr_t a = *(--sp);
    *(sp++) = a + b;
}

const struct object o_add = { .code = code_add };

Within a code, you can get access to a pointer to the current object with *ip.

Let’s see how we could handle subroutines. The code of a subroutine objects should bump the ip and push it on the return stack, and change ip to point to the payload. Each subroutine should end with a return primitive that pops the return address and change ip back:

void code_subroutine(void) {
    const struct object *self = *ip;
    ip++;
    *(rsp++) = ip;
    ip = self->payload;
}

void code_return(void) {
    ip = *(--rsp);
}

const struct object o_return = { .code = code_return };

And now a subroutine could look like

const struct object o_two = {
    .code = code_subroutine,
    .payload = { &o_one, &o_one, &o_add, &o_return },
};

The interpreter is largely unchanged, just with an additional dereferencing on ip. Starting the interpreter is slightly tricky. Where do you point ip initially?

If you have an object that’s the “main program” o_main, you can store &o_main in memory and let ip point to that. Be careful — the main program must not return because it has nowhere to return to.

const struct object *const start = &o_main;
const struct object *const *ip = &start;

void interpreter(void) {
    for (;;)
        (*ip)->code();
}

Primitive-centric threaded code

There are two issues with indirect threaded code from the previous section:

• The extra pointer indirection might be unsatisfactory for efficiency reasons.
• There’s no easy way to encode an immediate operand.

We can solve both problems with yet another spin on threaded code. M. Anton Ertl, in implementing Gforth, used what was referred to as “primitive-centric threaded code”. It is essentially a fat pointer scheme:

typedef void (*codeptr)(uintptr_t);

struct instr {
    codeptr code;
    uintptr_t data;
};

Instead of requiring a dereference of a point to access an object, the program directly stores a function pointer and one pointer worth of extra data. When processing each “instruction” in the program, the interpreter provides the extra data to the function.

const struct instr i_main = { ... };
const struct instr *ip = &i_main; // Changed!

uintptr_t stack_buf[STACK_SIZE];
uintptr_t *sp = stack_buf;

// Changed to adapt to match the type of ip
const struct instr *rstack_buf[STACK_SIZE];
const struct instr **rsp = rstack_buf;

void interpreter(void) {
    for (;;) {
        struct instr ins = *ip;
        ins.code(ins.data);
    }
}

It’s now possible again to make a generic “push”, without requiring separate code for every possible immediate value:

void code_push(uintptr_t data) {
    ip++;
    *(sp++) = data;
}

const struct instr i_one = { .code = code_push, .data = 1 };
const struct instr i_two = { .code = code_push, .data = 2 };

Subroutine calls can be made by making data point to an array of instructions making up the subroutines:

void code_subroutine(uintptr_t data) {
    const struct instr *sr = (const struct instr *) data;
    ip++;
    *(rsp++) = ip;
    ip = sr;
}

void code_return(uintptr_t data) {
    ip = *(--rsp);
}

const struct instr sr_three[] = {
    { .code = code_push, .data = 1 },
    { .code = code_push, .data = 2 },
    { .code = code_add },
    { .code = code_return },
};

const struct instr sr_six[] = {
    { .code = code_subroutine, .data = (uintptr_t) sr_three },
    { .code = code_subroutine, .data = (uintptr_t) sr_three },
    { .code = code_add },
    { .code = code_return },
};

Optimization

We can leverage a few tricks to convince the compiler into keeping our interpreter state in registers, and avoid doing a function call and return for each step.

Firstly, instead of using a loop to repeatedly call functions, we can instead make each piece of code tail call the next:

void code_foo(uintptr_t data) {
    // ...

    struct instr ins = *ip;
    ins.code(ins.data);
}

Compile your code with optimizations on. Your compiler should recognize that this is a tail call, and compile this down to a simpler indirect jump.

Next, instead of using global variables for the interpreter state, put them into arguments:

void code_foo(
    uintptr_t data,
    const struct instr *ip,
    uintptr_t *sp,
    const struct instr **rsp
) {
    // ...

    struct instr ins = *ip;
    ins.code(ins.data, ip, sp, rsp);
}

Using some macros would reduce the boilerplate a bit

#define DECL_STATE \
    const struct instr *ip, \
    uintptr_t *sp, \
    const struct instr **rsp

#define STATE ip, sp, rsp

void code_foo(uintptr_t data, DECL_STATE) {
    // ...

    struct instr ins = *ip;
    ins.code(ins.data, STATE);
}

On modern register-rich architectures (x86-64, ARM, RISC-V, MIPS, …), the arguments ip, sp, rsp would be passed in registers. Since ins.code expect these in the same registers, if your code leaves some of those state variables unchanged, there’s no cost to simply passing it on.

(On 32-bit x86, it might be possible with some non-portable __attribute__((regparm(4))) magic. I have not yet experimented with this.)

For threaded code, this is about as close as it gets to what you’d write in assembly. More native-code optimizations is possible, but would be out of the scope of (mostly) portable C.

Notes

The Threading section from the Gforth manual was very helpful when writing this article. In particular, the concept of primitive-centric threaded code is described in detail.

Complete demos corresponding to snippets in this article can be found on GitHub at dramforever/threaded-code-demo.

Consider this code, where one piece of global data is a pointer to another piece of global data:

void *foo;
void *bar = &foo;

During program execution, the memory at bar contains an address of foo. One way to achieve this is to require all the data to be loaded at a certain address. Then the linker can simply pre-calculate the address at link time and fill in the address for bar.

Having a program runnable from only one fixed address may be undesirable, however:

• If we’re a shared library, this would require a global registry of library addresses to avoid collision, and would be a massive pain.
• ASLR by definition requires randomized addresses and is in direct conflict of fixed addresses.
• In early boot scenarios such as bootloaders or EFI applications or drivers, virtual memory is not available, and it’s desirable to place executables out of the way of one another at runtime.

If something can work at any (suitably aligned) address, it is position-independent. Otherwise it’s position-dependent.

By compiling code to use PC-relative addressing, executable code can be made position-independent relatively easily. (Ha!) However the problem with global pointers is more fundamental. Again, take a look back at the code:

void *foo;
void *bar = &foo;

If we don’t want to change the representation of a void *, and the address of global data is only known at runtime, something has to, at runtime, figure out the address of foo and put it in bar before user code can see it.

Relative relocations

On ELF systems, this problem is handled with dynamic relocations. We’ll tackle the most simple case here: relative relocations.

We’ll handle the simplest case and assume everything (code, data) in an executable must still be contiguous and cannot move relative to one another. The entire executable will move as a whole to some “base address” that is only known at runtime. Then everything in the executable will be at a fixed offset from the base address.

We will also not need to link to dynamic shared libraries, and everything we need is in the executable. This is known as a statically-linked position-independent executable, or static-pie.

Conceptually, the three major steps that occur to make the code example work are:

1. Compiler: Generates a relocatable file (object file) with static relocations saying this:

   (8 bytes) // foo
   (8 bytes) // bar, Please fill in the address of foo

2. Linker: Places everything the compiler says to place at offsets from the base and generates a static-pie with dynamic relocations:

   offset       contents
   0x100        (8 bytes)
   0x108        (8 bytes) // Please fill in value of (base + 0x100)

3. Startup code: Figures out base, looks at the dynamic relocations, and fills in the correct addresses:

   addr         contents
   0xabc100     0
   0xabc108     0xabc100

We’ll ignore the relocatable file and focus on the static-pie.

RELA and REL

An instruction like “please fill in value of (base + one_offset) at (base + another_offset)” is called a relocation. The most obvious way to encode such a relocation is to just have a table of offsets. Like maybe an array of “RELA” entries:

struct {
    uintptr_t offset;
    uintptr_t info;
    intptr_t addend;
}

info encodes information. The low 8 (for 32-bit ELF) or 32 (for 64-bit ELF) bits encodes the type of relocation and higher bits is a symbol index. For our purposes the type is just R_*_RELATIVE, and since it’s just an offset and there’s no symbol, all the higher bits are 0.

(In elf.h speak, ELF*_R_INFO(sym, type) encodes the symbol index and relocation type into info (* is 32 or 64), and ELF*_R_TYPE(info), ELF*_R_SYM(info) unpacks the fields back.)

offset is the offset from the base address to which the entry applies to, and the addend is… the value to be added, in this case added to the base address.

(Note: The same structure is used for static relocations but the meanings of fields are not identical. That’s irrelevant to this article.)

To put everything together again, for each entry in the array, if info == R_*_RELATIVE, then it means “Please fill in the value of (base + addend) at (base + offset)”. The algorithm to run to apply these relocations is also pretty simple:

uintptr_t base = ...;
for (rela = ...) {
    if (ELF*_R_TYPE(rela->info) == R_*_RELATIVE) {
        *(uintptr_t *)(base + rela->offset) = base + rela->addend;
    } else ...
}

On some architectures a simplified structure “REL” is used, like:

struct {
    uintptr_t offset;
    uintptr_t info;
}

The addend field is gone from the table, and is just stashed into where offset points. The meaning of entries is otherwise the same.

for (rel = ...) {
    if (ELF*_R_TYPE(rel->info) == R_*_RELATIVE) {
        *(uintptr_t *)(base + rel->offset) += base;
    } else ...
}

The .rel[a].dyn section, and DT_REL[A]*

The linker synthesizes an array of tag-value pairs of dynamic linking information, and also synthesizes a symbol _DYNAMIC to point to the start of it:

struct {
    uintptr_t tag;
    uintptr_t value;
} _DYNAMIC[];

The format of the dynamic array does not have an explicit size and is terminated by an entry with tag as DT_NULL = 0. The relevant tags for us are:

• tag is DT_RELA = 7, value is offset of array of RELA entries
• tag is DT_RELASZ = 8, value is total size in bytes of the array of RELA entries
• tag is DT_RELAENT = 9, value is the size in bytes of one RELA entry. If there ever is a future need for extending the contents RELA entry, this will grow larger.

This allows us to find where the array of RELA entries is. We can just find _DYNAMIC and the base address using PC-relative addressing, and we can run the relocation algorithm from the previous section.

// Find these from _DYNAMIC
size_t dt_rela, dt_relasz, dt_relaent;

for (char *ptr = (char*)(dt_rela + base);
    ptr < (char*)(base + dt_rela + dt_relasz);
    ptr += dt_relaent) {
    Rela *rela = (Rela*)ptr;

    // Handle rela
}

Perhaps just for convenience, the linker puts the _DYNAMIC array in a section called .dynamic, and the dynamic RELA relocations in .rela.dyn.

(If you have an operating system giving you ELF auxillary vectors, you can look up the base address as AT_BASE, and look up where _DYNAMIC is by looking for AT_PHDR to find the PT_DYNAMIC segment. I suppose this is more portable.)

A similar thing happens for REL, with the .rel.dyn section, and tags DT_REL = 17, DT_RELSZ = 18, DT_RELENT = 19. Not much more to say about those.

Linker script trickery for the .rel[a].dyn section

If you’re building a bootloader or something and just want to, you don’t have to use _DYNAMIC. You can just use the linker script to give you symbols that bound the .rel[a] array.

.rela.dyn : {
    __rela_start = .;
    *(.rela*)
    __rela_end = .;
}

RELR

The RELA format is grossly inefficient space-wise at representing relocations. REL is 1/3 better but is only really a thing on some architectures. Can we do even better?

For position independent executables it is often the case that there are a lot of contiguous addresses needing relative relocation. For example, this is one relocation per every string:

const char *string_table = {
    "one string",
    "another string",
    "a third string",
    ...
};

RELR is a new packed format to store dynamic relative relocations more efficiently with bitmaps. From what I can tell it’s not really well documented, but support exists in e.g. glibc and musl. The linker LLD supports it fully. BFD ld supports it for x86 only.

The closest to an official documentation is one email on the general-abi mailing list that is a proposal for the RELR format.

Update 2025-06-02: DannyNiu/NJF informed me that Xinuos Inc., the company that has been most recently maintaining the ELF gABI, has, after nearly a decade of silence, published a new draft version at https://gabi.xinuos.com, which includes a section “Relative Relocation Table” describing RELR. This is the official specification of RELR.

The idea originates from Google for their Android stuff, but the format eventually settled on is this:

• Each entry is uintptr_t long.
• If an entry is even, it means the uintptr_t at this address needs relocating.
• If an entry is odd, the bits except the least significant bit, from lowest to highest, is a bitmap encoding which of the sizeof(uintptr_t) * 8 - 1 uintptr_t values after the last address handled needs relocating.

(It is simply assumed that all offsets needing relocation is aligned.)

For example, on a 64-bit system, if we want 64 contiguous relocations, we can just represent it with two entries:

0x0000_0000_0001_0000   The one uintptr_t at offset 0x10000 needs relocating
0xffff_ffff_ffff_ffff   The next 63 uintptr_t values after that needs relocating
                        (Offset 0x10008 through 0x101f8)

The last address handled is 0x101f8, so if the next entry is still a bitmap it would start from 0x10200. If we want one more relocation, making it 65 instead of 64:

0x0000_0000_0000_0003   Of the next 63 words, only the first one needs relocating
                        (Offset 0x10200)

(Remember that the least significant bit isn’t part of the bitmap.)

Even though bitmap only has one bit set, it still handles 63 uintptr_t values, so if the next entry is still a bitmap it would start from 0x103f8.

If we want to skip to another address, just put in the address. In fact if you want to be lazy and don’t want to figure out how to generate bitmaps, you can skip this altogether and just put down a list of addresses, and it’s still valid.

As simple as RELR is, the savings are remarkable. For our example, 65 relocations are represented with 24 bytes with RELR. In RELA that’s 1560 bytes. This is a space saving of 98%. According to some measurements this saves around 5% to 20% of binary size for PIEs. On most modern computers it is likely that the more compact in-memory representation is also faster due to less memory accesses.

The algorithm in more detail is like this:

uintptr_t next; // Next address to relocate
for (uintptr_t entry ...) {
    if ((entry & 1) == 0) {
        *(uintptr_t *)(base + entry) += base; // Like REL

        // Next to relocate is the word after the one pointed to by entry
        next = base + entry + sizeof(uintptr_t);
    } else {
        // The bitmap handles the next (sizeof(uintptr_t) * 8 - 1) words
        for (i = 0; i < sizeof(uintptr_t) * 8 - 1; i ++) {
            if ((entry >> (i + 1)) & 1) {
                // If bit (i + 1) is set, word i needs relocating
                *(uintptr_t *)(next + sizeof(uintptr_t) * i) += base;
            }
        }

        // Next to relocate is after that
        next += sizeof(uintptr_t) * (8 * sizeof(uintptr_t) - 1);
    }
}

For the bitmap case, it might be more convenient to write it like this:

        uintptr_t tmp = next;
        for (; entry >>= 1; tmp += sizeof(uintptr_t)) {
            if (entry & 1) {
                *(uintptr_t *)tmp += base;
            }
        }

        next += sizeof(uintptr_t) * (8 * sizeof(uintptr_t) - 1);

RELR uses .relr.dyn section and tags DT_RELR = 36, DT_RELRSZ = 35, DT_RELRENT = 37. (Note: The values aren’t sequential!) Contrary to RELA, and most struct arrays in ELF, for that matter, RELR doesn’t seem to designed to be extensible, since it’s just a compact form of REL.

Since only dynamic relative relocations are represented in RELR, it does not replace RELA/REL. The proposal states that dynamic RELR relocations should be processed before REL/RELA.

A note on “base address”

The base address mentioned above is not actually the start of the binary, but the offset of which the segments in a PIE (or shared library) has been moved, so real_address - segment_address. Since PIEs are usually linked to starting at 0 this checks out. If your linker script links everything starting at somewhere else, like:

SECTIONS {
    . = 0x80000000;
    __executable_start = .;

    // ...
}

The base address is actually real __executable_start - 0x80000000. No idea why you would do that though, since the whole point of PIE is to not have a fixed start address…

References

• Relative relocations and RELR by MaskRay
• arm64: Add support for relocating the kernel with RELR relocations by Peter Collingbourne
• Linker and Libraries Guide, Oracle Solaris 11 Information Library

The research that went into this article began as a simple technical question: How do I connect to the JTAG debug port on the VisionFive?

When luojia asked this very question on the support forum, the only responses were, surprisingly, discouragement. However, for any low-level software development, such a debug port is pretty much the only way to sanely, well, debug anything at all. Even though printf debugging was technically possible, it is still worth it to see if we can reach it over JTAG, given that the board is supposed to have JTAG connectors.

VisionFive

The development board in question, VisionFive, is a RISC-V single-board computer from StarFive. At its core is a StarFive JH7100 SoC, with two SiFive U74 cores and one E24 core.

(As of writing, the version of VisionFive currently available is also known as ‘VisionFive V1’, though even official documentation often omits the version number. The name ‘VisionFive’ in this article consistently refers to VisionFive V1, in case confusion arises in the future.)

The same processor core is also found on the HiFive Unmatched, on which the main SoC has four U74 cores and one S7 core. Unmatched had more RAM and better peripherals, and was made in the form factor of a regular PC motherboard. VisionFive is, instead, clearly intended for a slightly lower end market, or for those who prefers a palm-sized Raspberry Pi lookalike.

JTAG on the VisionFive, or not

For our purposes, the one main difference between the Unmatched and the VisionFive is how the JTAG port is connected. On the Unmatched, an FT2322H adapter on-board means that the Micro-USB port gives access to both the UART port and the JTAG port, readily usable with riscv-openocd.

On the VisionFive, however, JTAG access seems… elusive. Nowhere in the documentation is the JTAG port on-board mentioned. On drawings of the board, the words JTAG are written next to the PMIC, which is, at least to me, nonsensical, as there are no notable ports to be found there.

Next to the color-coded (nice!) 40-pin header though, one can find seven plated holes, one of them having a square outline. Browsing through the schematic reveals that this is indeed where the JTAG port is connected.

Problem solved, right? Solder up some header pins or build a pogo-pin rig, and just connect it up to your workstation with an FT2322H, and we have JTAG.

Or so we thought. Unfortunately, this JTAG ports does not seem to respond at all to any input. It seems as if this port isn’t connected at all.

Finding the JTAG port

Chasing through labels on the schematics reveals that the JTAG_* through-holes connect to a level shifter, which presents the SoC with 1.8 V signals instead of 3.3 V ones. They then connect to pads on the SoC, mysteriously named GPIOxx/U74_JTAG_*.

So are these GPIO or JTAG? Thankfully the pad connections have labels with positions, so we can look them up on the datasheet. For example, A25 is described as…

A25     GPIO[0]     IO      function IO share with GPIO

‘Function IO Share’ is the title of section 11 in the datasheet. One register, named IO_PADSHARE_SEL, has one of 7 valid values, 0 through 6, is a global configuration controlling the functions two-hundred-odd pads PAD_FUNC_SHARE[141:0] and PAD_GPIO[63:0]. Each of the configurations is called a ‘signal group’, and the groups themselves are called ‘Function 0’ through ‘Function 7’. A giant table then follows, showing each pad’s function under each signal group.

The pads PAD_GPIO[4:0] would be the connections we found earlier, and in Function 0, they. Since Function 0 is supposed to be the default value on reset, this means that we should see a JTAG port there, right?

At this point, the only thing I could think of is connecting to JTAG while holding down the reset button. However, since I had neither a JTAG adapter nor a VisionFive board, all I did was tell luojia about it, and moved on to finish my finals.

Digging deeper into the GPIO multiplexer

The single document that made the system ‘click’ for me is the devicetree documentation for starfive,jh7100-pinctrl. This node can be found in jh7100.dtsi, which is included in jh7100-starfive-visionfive-v1.dts:

gpio: pinctrl@11910000 {
    compatible = "starfive,jh7100-pinctrl";
    reg = <0x0 0x11910000 0x0 0x10000>,
          <0x0 0x11858000 0x0 0x1000>;
    reg-names = "gpio", "padctl";
    /* <snip> */
};

The address ranges mentioned here correspond to these rows in the datasheet:

SYSCTRL-IOPAD_CTRL  0x00_1185_8000  0x00_1185_BFFF  16KB
GPIO                0x00_1191_0000  0x00_1191_FFFF  64KB

These registers control the functions and states of PAD_GPIO[63:0] and PAD_FUNC_SHARE[141:0]. The following diagram is included in the devicetree bindings documentation:

                          Signal group 0, 1, ... or 6
                                 ___|___
                                |       |
    LCD output -----------------|       |
    CMOS Camera interface ------|       |--- PAD_GPIO[0]
    Ethernet PHY interface -----|  MUX  |--- PAD_GPIO[1]
      ...                       |       |      ...
                                |       |--- PAD_GPIO[63]
     -------- GPIO0 ------------|       |
    |  -------|-- GPIO1 --------|       |--- PAD_FUNC_SHARE[0]
    | |       |   |             |       |--- PAD_FUNC_SHARE[1]
    | |       |   |  ...        |       |       ...
    | |       |   |             |       |--- PAD_FUNC_SHARE[141]
    | |  -----|---|-- GPIO63 ---|       |
    | | |     |   |   |          -------
    UART0     UART1 --

These pads on the package, or ‘function IO share with GPIO’ as listed in the datasheet, are connected to the internal signals through a two-stage multiplexer:

First, as mentioned, the IO_PADSHARE_SEL register selects one of 7 ‘signal groups’. This is, curiously, a global setting, meaning that it affects all of the ‘function share’ pads at once. A huge table in the datasheet describes the function of each such pad’s function in each signal group. For example, the row in the table for PAG_GPIO[0] reads: (Reproduced here vertically for convenience)

Interface               GPIO
IO Name                 PAD_GPIO[0]
Function 0 (Default)    U74_JTAG_TDO
Function 1              GPIO0
Function 2              X2C_TX_DATA3
Function 3              LCD_DATA4
Function 4              X2C_TX_DATA3
Function 5              PLL_RFSLIP[0]
Function 6              MIPITX_MPOSV[0]

Note that GPIOn has no direct correspondence to PAD_GPIO[n]. For example, PAD_FUNC_SHARE[0] can also be connected to GPIO0:

Interface               ChipLink
IO Name                 PAD_FUNC_SHARE[0]
Function 0 (Default)    X2C_TX_CLK
Function 1              LCD_CLK
Function 2              CM_CLK
Function 3              X2C_TX_CLK
Function 4              GPIO0
Function 5              GPIO0
Function 6              GPIO0

Instead, GPIOn are internal signals further multiplexed into internal inputs and outputs by the ‘GPIO FMUX’. Each of the GPIOn signals also has configurable pull up/down and Schmitt triggers, though not all options are available for all I/O pads.

After that, there are three connections to be made: output, output enable, and input. These are all configured from the destination side, so:

• Each GPIO output and output enable may be connected to either one of the internal outputs or a constant 0 or 1.
• Each internal input may be connected to one of the GPIO inputs, or a constant 0 or 1.

In addition, the input value from each GPIO may be read from MMIO registers GPIODIN_0 and GPIODIN_1, and it’s also possible to configure them to fire interrupts.

This allows quite a flexible usage of the GPIO internal signals. They can be selected to work with the 1.8 V or 3.3 V I/O pads, and can either be fully controlled by software with interrupt support, or connected to one of the internal I2C/I2S/SDIO/… controllers.

Curiously, in Function 0, the default mode for IO_PADSHARE_SEL, none of the GPIOn signals are connected to the I/O pads. Instead, some of the internal signals are directly connected to I/O pads. Moreover, in a few of the cases, the internal signals PAD_GPIO[n] connects to in Function 0 are conveniently also by default connected to the same-numbered internal GPIOn. For example, most relevant to our original use cases, in Function 0 these connections are made:

PAD_GPIO[0]         U74_JTAG_TDO
PAD_GPIO[1]         U74_JTAG_TCK
PAD_GPIO[2]         U74_JTAG_TDI
PAD_GPIO[3]         U74_JTAG_TMS
PAD_GPIO[4]         U74_JTAG_TRSTN

At the same time, the default GPIO FMUX configuration for these JTAG signals are:

CPU_JTAG_TDO        GPIO0
CPU_JTAG_TCK        GPIO1
CPU_JTAG_TDI        GPIO2
CPU_JTAG_TMS        GPIO3
CPU_JTAG_TRSTN      GPIO4

(It seems that CPU_JTAG_* are synonymous with U74_JTAG_*.)

Finding the JTAG port, take two

It seems that Function 0 is intended for booting and initialization, with many of the internal functions available on I/O pads right away without configuration. However given the lack of, well, actual general purpose input/output, there is no chance Linux runs in Function 0.

We already see our problem: The seven through-holes going to PAD_GPIO[4:0] are JTAG in Function 0 but might not be when another ‘Function’ is selected. This means that at some time after booting, IO_PADSHARE_SEL is set from 0 to some other value, and these JTAG-appearing through-holes would no longer be JTAG.

Which value is it then? Curiously, the example listed in the devicetree documentation has this property:

starfive,signal-group = <6>;

Which would suggest that Linux selects Function 6 at initialization, though the actual jh7100.dtsi did not have this property. The documentation indicates that in case the property is not specified, the IO_PADSHARE_SEL register is left unchanged:

starfive,signal-group:
  description: |
    Select one of the 7 signal groups. If this property is not set it
    defaults to the configuration already chosen by the earlier boot stages.
  $ref: /schemas/types.yaml#/definitions/uint32
  enum: [0, 1, 2, 3, 4, 5, 6]

After a short chat with luojia, who tried connecting to JTAG without a microSD card unsuccessfully, it is apparent that some earlier boot stage sets IO_PADSHARE_SEL. It did not take long crawling through the code provided by StarFive to find this particular line in secondBoot:

_SET_SYSCON_REG_register104_SCFG_io_padshare_sel(6);

For those not familiar with secondBoot, it is one of the first stages of bootloaders on the VisionFive, second to only the internal ROM.

All of the ‘Firmware’ stages run from an on-board QSPI flash, without requiring a microSD card present. This means that early on in the boot sequence, IO_PADSHARE_SEL is switched from 0 to 6, disabling the JTAG through-holes. Searching through the other files in this repository also reveals the undocumented address of IO_PADSHARE_SEL:

0x118581a0

There is still a way to confirm IO_PADSHARE_SEL. If you hold down the ‘Boot mode’ button while powering the board up, instead of following the normal boot process, a prompt appears on the ‘debug’ serial console port at 9600 8n1, running off internal ROM, where you can read and write arbitrary physical memory. At this point, NickCao helped me out by connecting to this ‘recovery console’, and reading IO_PADSHARE_SEL:

# rh 0x118581a0

 Read Half : 0x0000

Reading the same address in the U-Boot shell gives 6, confirming much of what we had seen.

Connecting to JTAG, for the first time

But wait, if IO_PADSHARE_SEL is 0 when running in internal ROM, does this mean JTAG is available on the seven through-holes? Should we be able to connect to the debug modules in this state?

I asked Icenowy, the only person I know of with both a VisionFive and some JTAG adapter handy to help out. I told them to power up the board with ‘Boot mode’ button held down, and then try connecting to JTAG. They came back with what was, at the time of writing, the first screenshot of GDB-over-OpenOCD connected to the JH7100, at least from what I could find on the Internet.

Among the addresses found in the registers are:

• 0x1840084c: Middle of internal ROM
• 0x1800ff80: Middle of intRAM0
• 0x1244000c: One of the UART3 registers

Finally, we have JTAG access to the VisionFive.

Finding the JTAG port, take three

Even though technically we’re connected to the debug module, running the SoC entirely in Function 0 isn’t really an option as the board doesn’t seem to be configured this way. Once we switch to Function 6 though, our connection would be cut off.

Where do the JTAG signals now go go? As mentioned earlier, the JTAG signals are mapped by default to GPIO0 through GPIO4. Since we’re now in Function 6, these GPIO signals correspond to I/O pads… (looks at datasheet) PAD_FUNC_SHARE[4:0], which are 3.3 V and connected on the schematic to nets confusingly named GPIO0 through GPIO4.

These nets are connected to the 40-pin Raspberry Pi compatible header at pins… Wait what?

For some reason, these pins are labelled on the schematic with JTAG signal names. On any other documentation, such as StarFive’s GPIO Header Guide, they are only referred to as GPIO0, etc. and nowhere is JTAG mentioned.

A straightforward test of connecting the JTAG adapter while the system is up and running showed that these five pins… do not respond to the JTAG adapter.

Confusingly, Icenowy found out that for a certain period during the boot process, they could connect through those pins on the 40-pin header. Before this period, JTAG is found on the seven through-holes, and after that, it just seems to… disappear. Perhaps somewhere in the boot process another piece of code configured the second-stage GPIO FMUX and disconnected the JTAG signals. It makes sense because it frees up five pins on the header for actual GPIO.

Finding the JTAG port, take four

Around the same time when I asked NickCao to confirm the value of IO_PADSHARE_SEL in U-Boot, I also asked them to check the GPIO FMUX configuration, which showed that JTAG signals are connected correctly to GPIO0 through GPIO4. Therefore, whatever changed the configuration must have come after. Linux it is.

As mentioned before, the devicetree node starfive,jh7100-pinctrl manages both layers of GPIO multiplexing. The driver itself can be found in drivers/pinctrl/pinctrl-starfive.c.

Initially, I had assumed that the driver in StarFive’s fork of Linux was identical to that found in mainline Linux 5.18, though I would soon be proven wrong. As I was browsing through the dts files hoping to gain some insight on why the JTAG signals were gone, a section in jh7100-starfive-visionfive-v1.dts caught my eye.

&gpio {
    /* don't reset gpio mux for serial console and reset gpio */
    starfive,keep-gpiomux = <13 14 63>;
};

There was no mention of starfive,keep-gpiomux in mainline Linux’s version of pinctrl-starfive, but these two lines in StarFive’s version seemed relevant.

if (!keepmux)
    starfive_pinmux_reset(sfp);

keepmux is a module option defined as:

static bool keepmux;
module_param(keepmux, bool, 0644);
MODULE_PARM_DESC(keepmux, "Keep pinmux settings from previous boot stage");

starfive_pinmux_reset disables the inputs and outputs associated with every GPIOn signal, unless n was mentioned in starfive,keep-gpiomux.

The next step was clear: Boot with the kernel command line option pinctrl-starfive.keepmux=1, or modify jh7100-starfive-visionfive-v1.dts and add the JTAG signals to starfive,keep-gpiomux:

    starfive,keep-gpiomux = <0 1 2 3 4 13 14 63>;

Connecting to VisionFive with OpenOCD

At this point I borrowed the board from NickCao, and used a Raspberry Pi as an adapter to connect to it, over the JTAG pins on the 40-pin connector. Two TAPs can be found on the JTAG port, the first of which connects to the E24 core, and the second connects to the two U74 cores. This was my OpenOCD configuration file:

adapter driver linuxgpiod

linuxgpiod gpiochip 0
linuxgpiod jtag_nums 11 25 10 9
linuxgpiod trst_num 7

reset_config trst_only

transport select jtag

jtag newtap e24 cpu -irlen 5 -expected-id 0x200005fd
jtag newtap u74 cpu -irlen 5 -expected-id 0x200003fd

target create e24.cpu0 riscv -chain-position e24.cpu -coreid 0
target create u74.cpu0 riscv -chain-position u74.cpu -coreid 0 -rtos hwthread
target create u74.cpu1 riscv -chain-position u74.cpu -coreid 1
target smp u74.cpu0 u74.cpu1

init

Before Linux boots, I was able to connect to all of these cores, and read some information off of them. For example, reading CSRs from the U74 cores:

As expected, this is a SiFive (mvendorid = 0x489) 7-series (marchid = (1 << 63) | 7) core, version 19.05 (mimpid = 0x20190531). Seen from the ISA implemented, namely RV64GC with Supervisor/User, this was certainly a U74 core.

After Linux starts, however, the E24 core seems to start misbehaving. OpenOCD starts generating error messages like:

Warn : target e24.cpu0 examination failed
Error: [e24.cpu0] DMI operation didn't complete in 2 seconds. The target is either really slow or broken. You could increase the timeout with riscv set_command_timeout_sec.

It seems that the E24 core had been disconnected or disabled. In any case, it was not responding. OpenOCD was confused by this lack of response and debugging on the U74 was also affected:

Commenting out the e24.cpu0 line in the config would ignore the E24 core and work around this issue.

# target create e24.cpu0 riscv -chain-position e24.cpu -coreid 0

What is going on with the E24 core? Seeing that the main star of the show, the dual U74 cores, have already been ‘conquered’, it’s probably an appropriate time to take a break. This article has already been filled with too many details, so we will look at the E24 ‘microcontroller’ core next time, as a side quest, in a future post.

(By the way: It seems that beta/sample versions of the now cancelled BeagleV Starlight board has a very similar JTAG configuration. If anyone still has one of these boards, it would be extremely interesting to try it out.)

To be continued…

References

• JH7100 documentation: https://github.com/starfive-tech/JH7100_Docs
• VisionFive schematics: https://github.com/starfive-tech/VisionFive
• JH7100 ‘secondBoot’ bootloader: https://github.com/starfive-tech/JH7100_secondBoot
• SiFive U74 Core Complex Manual: https://sifive.cdn.prismic.io/sifive/ad5577a0-9a00-45c9-a5d0-424a3d586060_u74_core_complex_manual_21G3.pdf
• Files found in VisionFive Linux source code, provided by StarFive:
  • include/dt-bindings/pinctrl/pinctrl-starfive.h
  • drivers/pinctrl/pinctrl-starfive.c
  • Documentation/devicetree/bindings/pinctrl/starfive,jh7100-pinctrl.yaml
  • arch/riscv/boot/dts/starfive/jh7100.dtsi
  • arch/riscv/boot/dts/starfive/jh7100-starfive-visionfive-v1.dts

I made a post to StarFive’s RVSpace forum with a how-to of connecting to VisionFive’s JTAG port, hoping it would help those looking to do low-level work on the board: https://forum.rvspace.org/t/connecting-to-visionfive-s-jtag-port-a-short-guide/514.

Acknowledgements

I would like to thank these people for helping out during the research:

• NickCao (GitHub: @NickCao)
• luojia (GitHub: @luojia65)
• Icenowy (GitHub: @Icenowy)

A friend of mine bought a motorized adjustable desk a long time ago and recently got the idea to hook up the controller to the Internet for some reason. They tapped the wire coming from the controls panel with a logic analyzer and was able to capture some packets, hexdumps shown:

AAFF 0040 2EEC
AAFF 0060 2964
AAFF 0050 2B08
AAFF 040E02 0450
AAFF 050E02 8EDA
AAFF 060E02 1D05
AAFF 070E02 978F
... (and many more samples)

They were reasonably sure that the framing was correctly decoded, meaning that each line of hexdump is exactly one complete transmission. The message format of two bytes of (seemingly fixed) header, variable number of bytes of message, and two bytes of checksum resembles Modbus RTU.

An implementation of the Modbus CRC-16, however, gives check sequences that don’t match up with what we see. It’s still suspiciously like some sort of CRC-16 though, so I decided to go though with the assumption that it is a CRC-16 variant waiting to be discovered.

But what is a CRC anyway?

The cyclic redundancy check (CRC) is a family of error-checking codes that is widely used to detect inadvertent data corruption of data during transmission or in storage. The most common way a CRC is implemented is using a linear feedback shift register (LFSR), and the mathematical structure of it is taking the remainder of a polynomial division, where the polynomial is defined in $\mathrm{GF}(2)$.

Let’s go into details of how CRCs work in practice, in particular how the details of the algorithms maps to polynomials, and how we can manipulate CRCs using its properties, along with how I applied the ideas while reverse engineering the exact parameters used for my friend’s desk.

Mathematical basics

Just for a warm up, let’s go into some basics of how polynomials work. These things are immensely useful in various fields of computer science because they provide an interesting way to work with bit strings, so it can’t hurt to take a closer look.

The Galois field $\mathrm{GF}(2)$

$GF(2)$ might have a scary name, but it really is just the integers modulo $2$. This field only has two elements, $0$ and $1$. Thinking of them as logical bits, addition is exclusive-or (xor), and multiplication is logical ‘and’. Anything added with itself is gone, and subtraction is the same as addition:

• $a + a = 0$
• $a + b = a - b$

Polynomials in $\mathrm{GF}(2)$, in particular univariate polynomials in $x$, called $\mathrm{GF}(2)[x]$, is what we’re interested in here. In particular, since the coefficients of the terms are either $0$ or $1$, we can write them as if each term just exists or doesn’t exist, like:

$$x^{16} + x^{3} + x^{1} + x^{0}$$

(Side note: Polynomials are not polynomial functions. There are only $4$ functions of $\mathrm{GF}(2) \to \mathrm{GF}(2)$, but if the term coefficients of two polynomials differ they are not the same polynomial, regardless of whether they correspond to the same function.)

We can the coefficients of a polynomial into a bit string, highest power term first, omitting (the infinite sequence of) leading zeros. For example, the above example corresponds to:

1 0000 0000 0000 1011

We can then read that as an (unsigned) integer in binary, which is a convenient representation of $\mathrm{GF}(2)[x]$ polynomials in computers.

Polynomial addition and multiplication

Addition and multiplications work exactly as we expect, if you take care that the coefficients should be calculated modulo 2. As we all know, $2 = 0$, so each term will cancel with itself:

$$x^{n} + x^{n} = x^{n} - x^{n} = 0$$

So for example:

$$(x^{4} + x^{2}) + (x^{2} + x^{0}) = x^{4} + 2 x^{2} + x^{0} = x^{4} + x^{0}$$

Addition and multiplication have the commutativity, associativity and distributivity properties we all know and love.

Using the representation of polynomials as unsigned integers, polynomial addition is just bitwise-xor. Meanwhile, multiplication is known as ‘carry-less multiplication’, which is often available as dedicated instructions in modern CPUs for cryptographic applications.

Polynomial (Euclidean) division

What we’re concerned here most, when working with CRCs, is polynomial division. It is defined analogously to integer division with remainder, except instead of comparing the magnitude of numbers, we compare the degree of polynomials.

Given two polynomials $a(x)$ and $b(x)$ (where $b(x) \ne 0$), there is only one quotient $q(x)$ and remainder $r(x)$ such that $r(x)$ has strictly smaller degree than $b(x)$, and:

$$a(x) = b(x) q(x) + r(x)$$

The algorithm to figure out $q(x)$ and $r(x)$ is a variation on the integer long division algorithm. In particular, we don’t usually care about $q(x)$, so it is fairly easy to ‘reduce’ $a(x)$ with multiples of $b(x)$ until the degree is strictly less than $b(x)$. Moreover, since the only possible non-zero coefficient is $1$, we don’t even need a division to figure out the scalar to multiply $b(x) x^k$ by.

a = (polynomial dividend)
b = (polynomial divisor)

while (degree of a) >= (degree of b):
    a = a + b x^((degree of a) - (degree of b))

return a

In Python for example, the int.bit_length method returns the length of an integer in binary representation, excluding leading zeros. It is one more than the polynomial’s degree, which is not important in our case:

def poly_mod(a, b):
    while a.bit_length() >= b.bit_length():
        a ^= b << (a.bit_length() - b.bit_length())
    return a

For convenience we can use $a(x) \bmod b(x)$ to refer to $r(x)$.

One notable thing is that adding two polynomials together doesn’t increase the degree, so:

$$(u + v) \bmod b = (u \bmod b) + (v \bmod b)$$

Cyclic redundancy checks

Basic CRCs

For a message consisting of bytes, we can also convert it to a bit string, by putting each byte in order, and for each byte, put the least significant bit first. So f0 30 becomes 0000 1111 0000 1100.

For simplicity, consider this CRC generation code, with a single parameter tap:

crc = 0

for each bit b in message:
    crc = crc ^ b
    if least significant bit of crc is 1:
        crc = (crc >> 1) ^ tap
    else:
        crc = crc >> 1

return crc

This structure is called a linear feedback shift register, or LFSR. We can try to reverse engineer this in terms of polynomials in $\mathrm{GF}(2)$.

As the message is read in bit by bit, we can say that the ‘current polynomial’ starts at $0$, and for each bit $b$ we read, we update the polynomial from $m$ to $mx + b$. This continues until the message is completely read, and $m$ is the polynomial corresponding to the entire message.

Since the crc ‘register’ is constantly being shifted to the right, it actually contains a ‘bit reversed’ polynomial. The least significant bit is actually the highest power term. So similarly, if tap were some polynomial, it should also be bit reversed. For convenience, say crc and tap are $N$-bit integers.

The ‘bit reversed’ part is not weird anymore if we write the integer crc as an $N$ bit integer in little endian as a bit string and find the corresponding polynomial. It is the correct polynomial we’re looking for.

We can start interpreting the bit operations taken:

• For each bit $b$ in message:
  • $\mathtt{crc} \leftarrow \mathtt{crc} + b x^{N - 1}$
  • If the $x^{N - 1}$ coefficient of $\mathtt{crc}$ is $1$, then $\mathtt{crc} \leftarrow \mathtt{crc} \cdot x + x^N + \mathtt{tap}$
  • Else: $\mathtt{crc} \leftarrow \mathtt{crc} \cdot x$

Noting that for the operation crc >> 1, it discards the least significant bit if it’s zero. So in terms of polynomials, this means that a $x^N$ term cannot occur in $\mathtt{crc}$ and would be discarded. That’s what adding (or really, subtracting) $x^n$ means.

A bit of distributing gives:

• For each bit $b$ in message:
  • $\mathtt{crc} \leftarrow \mathtt{crc} \cdot x + b x^N$
  • If the $x^N$ coefficient of $\mathtt{crc}$ is $1$, then $\mathtt{crc} \leftarrow \mathtt{crc} + x^N + \mathtt{tap}$

Each time a $b$ term is shifted into $m$, $m$ turns into $mx + b$, and, $\mathtt{crc}$ is turned into $\mathtt{crc} \cdot x + b x^N$. If we don’t bother with the ‘if’ step, then after reading everything $\mathtt{crc} = m x^N$.

But after reading each bit, $x^N + \mathtt{tap}$ is either added or not. This means $\mathtt{crc}$ and $m x^N$ are actually only equal modulo $x^N + \mathtt{tap}$. Also notice that $\mathtt{crc}$ has degree strictly smaller than $N$. Therefore:

$$\mathtt{crc} = (m x^N) \bmod (\mathtt{tap} + x^N)$$

Realistic CRCs

Realistic CRCs have a few more parameters. I call them init and final.

crc = init

for each bit b in message:
    crc = crc ^ b
    if least significant bit of crc is 1:
        crc = (crc >> 1) ^ tap
    else:
        crc = crc >> 1

return crc ^ final

(Side note: A particular may also reverse or not reverse the order of the bits on input, and may reverse or not reverse the bit order of crc. In practice, these options have not shown up at least for me, and only takes 4 tries to brute force, so they’re not considered.)

Just like before, we notice that if we don’t do the ‘reduction’ step, $\mathtt{crc} = \mathtt{init} \cdot x^L + m x^N$, where $L$ is the length of the message, this time counting leading zeros. A $\mathtt{final}$ thing is added to the result.

Suppose that $\mathtt{init}$ and $\mathtt{final}$ have degree less than $N$, then:

$$\mathtt{crc} = (m x^N + \mathtt{init} \cdot x^L + \mathtt{final}) \bmod (\mathtt{tap} + x^N)$$

We note that the previous zero-initialized CRC does not depend on $L$, which means that it cannot detect extra/missing leading zeros. A non-zero init mitigates this. I have absolutely no idea what final is supposed to achieve, but it’s just there.

From now on, we’ll use these symbols consistently:

• $L$ (length) is the message length in bits
• $m$ (message) is the message bit string as a polynomial
• $N$ is the length of the CRC
• $r$ (remainder) is $\mathtt{crc}$
• $F$ is $\mathtt{final}$
• $I$ is $\mathtt{init}$
• $P$ (polynomial) is $\mathtt{tap} + x^N$

Now the equation for a realistic CRC can be written:

$$r = (m x^N + I x^L + F) \bmod P$$

The following one just means both sides are equal after doing a $\bmod P$. If you’re familiar with modulo congruences in integers, it’s basically the same thing.

$$r \equiv m x^N + I x^L + F \pmod P$$

Linearity properties of CRCs

CRCs are linear

(Or affine, if you’re pedantic)

Suppose we have two messages $m_1$ and $m_2$ of the same length $L$, with CRCs $r_1$ and $r_2$ respectively.

$$\begin{aligned} r_1 &\equiv m_1 x^N + I x^L + F \pmod{P} \\ r_2 &\equiv m_2 x^N + I x^L + F \pmod{P} \end{aligned}$$

Adding the two equations together gives something quite nice (remember, anything added with itself equals zero):

$$r_1 + r_2 \equiv (m_1 + m_2) x^N \pmod{P}$$

Suppose that we have another pair of messages $m_3$ and $m_4$, still with lengths $L$, such that $m_1 + m_2 = m_3 + m_4$, i.e. the four messages bitwise-xor to all zeros. Then we have:

$$r_1 + r_2 \equiv (m_1 + m_2) x^N \equiv (m_3 + m_4) x^N \equiv r_3 + r_4 \pmod{P}$$

This is actually fairly common. For example, with consecutive numbers as strings:

• $m_1$ is ASCII 10, binary 1000 1100 0000 1100
• $m_2$ is ASCII 11, binary 1000 1100 1000 1100
• $m_3$ is ASCII 12, binary 0100 1100 1000 1100
• $m_4$ is ASCII 13, binary 1100 1100 1000 1100

Or, taking these four message hexdumps from the samples:

AAFF 040E02 0450
AAFF 050E02 8EDA
AAFF 060E02 1D05
AAFF 070E02 978F

The messages match up just like the consecutive numbers example above, and the check sequences also match up. That’s some encouraging confirmation that we’re indeed looking at a CRC.

(I guess technically this kind of property should be called ‘affine’ instead of ‘linear’, but, meh…)

Applications

This property is tremendously useful if we actually know the parameters of a certain CRC algorithm. For example, going back to bitwise land, if we have two messages $a$ and $b$ of the same length, and $z$ is the all-zeros messages of that length, then:

$$\mathrm{crc}(a \oplus b) = \mathrm{crc}(a) \oplus \mathrm{crc}(b) \oplus \mathrm{crc}(z)$$

Suppose for some inexplicable reason, someone uses a CRC-32 as a hash function to hash string representations of integers, as an attempt to hide the original numbers:

crc("123456") = 0x0972d361

The number can range up to 10 digits, so they’re hoping that we can’t brute force our way through a billion numbers to find a match.

Nobody with even a tiny bit of sanity would think that’s a reasonable way to hide a number… Right?

(Right? I suppose that’s a story for another time…)

To reverse the digit string out of the CRC, we can do a meet-in-the-middle attack, matching up strings like 123\0\0\0 (that’s 123 then 3 NUL bytes) with \0\0\0456. The details are not that hard, and it takes milliseconds to ‘crack’ each hash (if memory serves). For collisions we also get every solution.

However in our case of the adjustable desk, we don’t actually know the parameters used. We must dig deeper. But before that, let’s take a detour into how CRCs are transmitted:

Messages with CRC appended

There’s another thing about how CRCs are implemented. Take a look back at the ‘CRC equation’

$$r \equiv m x^N + I x^L + F \pmod P$$

Let’s rearrange it a bit:

$$m x^N + r \equiv I x^L + F \pmod P$$

The right hand side only depends on the message length, and the left hand side… It’s the message with $N$ zeros appended, then bitwise-xor with the CRC, i.e. exactly the message and the CRC concatenated. If you like thinking of CRCs as integers, that’s the messages concatenated with the CRC in little endian.

It is not a coincidence that CRCs are often concatenated after the message in this exact way. Due to this nice property, this concatenation simplifies CRC checking hardware, which need not keep track of a ‘state’ of whether it’s reading data or reading the CRC, and only need an end-of-stream signal. We’ll not go into detail on that, but just notice that each line in our hexdump:

AAFF 0040 2EEC

Is already the polynomial $m x^N + r$.

Messages with equal length

In our case, we know several pairs of messages and their correct CRCs. We can work out a fair bit of information by comparing messages. We’ll first focus on pairs of messages with equal length.

Comparing several equal-length messages

Given two messages $m_1$ and $m_2$ with equal length $L$, and known CRCs $r_1$ and $r_2$,

$$\begin{aligned} m_1 x^N + r_1 &\equiv I x^L + F \pmod{P} \\ m_2 x^N + r_2 &\equiv I x^L + F \pmod{P} \end{aligned}$$

Adding the two equations together give:

$$(m_1 x^N + r_1) + (m_2 x^N + r_2) \equiv 0 \pmod{P}$$

Similarly, if we have more messages $m_3$, $m_4$, etc. still of length $L$, we have:

$$\begin{aligned} (m_1 x^N + r_1) + (m_3 x^N + r_3) \equiv 0 \pmod{P} \\ (m_1 x^N + r_1) + (m_4 x^N + r_4) \equiv 0 \pmod{P} \end{aligned}$$

Actually, it only matters that for each pair used in this adding, the messages have the same length. The pairs don’t have to be all $L$. Let’s call $d_{k,l} = (m_k x^N + r_k) + (m_l x^N + r_l)$

Since all the $m_k x^N + r_k$ directly correspond to the data we dumped, we actually know them in full, not just modulo something. So we know all $d_{k, l}$ in full. If $m_k$ and $m_l$ have the same length then for some unknown $q_{k,l}$:

$$d_{k, l} = P \cdot q_{k, l}$$

We have several multiples of $P$. How can we find $P$ itself? This sounds like a job for…

Polynomial greatest common divisor (GCD)

So if we can calculate the remainder of polynomial division, is there an analogous Euclidean algorithm to calculate the greatest common divisor (GCD) of two polynomials? You bet:

def poly_gcd(a, b):
    while b != 0:
        a, b = b, poly_mod(a, b)
    return a

The GCD of two polynomials $a(x)$ and $b(x)$ is the polynomial $g(x)$ with the highest degree such that $a(x)$ and $b(x)$ are both the product $g(x)$ and another polynomial.

The Euclidean algorithm for finding GCD works with polynomials, just like with integers.

Finding $P$ with GCD

Since if we have examples of $P \cdot q_{k, l}$ available, even though all the $q_{k, l}$ are unknown, we should be able to take the GCD of all of them and hopefully get $P$.

So for example with these three message hexdumps:

m1, r1 = AAFF 0040 2EEC
m2, r2 = AAFF 0060 2964
m3, r3 = AAFF 0050 2B08

Pairing them up arbitrarily give these polynomials:

$$\begin{aligned} (m_1 x^{16} + r_1) + (m_2 x^{16} + r_2) &= x^{18} + x^{15} + x^{14} + x^{13} + x^{4} + x^{0} \\ (m_1 x^{16} + r_1) + (m_3 x^{16} + r_3) &= x^{19} + x^{15} + x^{13} + x^{5} + x^{2} + x^{1} + x^{0} \end{aligned}$$

They should both be a multiple of $P$, so taking the polynomial GCD should give us a multiple of $P$ of lower degree, hopefully $P$ itself.

What we get is:

$$x^{16} + x^{14} + x^{13} + x^{2} + x^{0}$$

Since we guessed that it’s a CRC-16, $P$ should have degree $N = 16$, and this result does have degree $16$. So that’s it, we found our polynomial $P = x^{16} + \mathtt{tap}$.

For use in code, tap should be the bit reversal of 0x6005, i.e. 0xa006.

Messages with unequal length

Comparing messages with unequal length

Having figured out $P$, we can try working on the rest of our parameters. We’ll pick two messages $m_1$ and $m_2$ with unequal lengths $L_1$ and $L_2$, and known CRCs $r_1$ and $r_2$,

$$\begin{aligned} m_1 x^N + r_1 &\equiv I x^{L_1} + F \pmod{P} \\ m_2 x^N + r_2 &\equiv I x^{L_2} + F \pmod{P} \end{aligned}$$

Adding them this time gives:

$$(m_1 x^N + r_1) + (m_2 x^N + r_2) \equiv I (x^{L_1} + x^{L_2}) \pmod{P}$$

Everything except $I$ is known here.

Solving for $I$

Suppose that:

$$I = \sum_{k = 0}^{N - 1} a_k x^k$$

Then:

$$I (x^{L_1} + x^{L_2}) \bmod P = \sum_{k = 0}^{N - 1} a_k \cdot (x^k (x^{L_1} + x^{L_2}) \bmod P)$$

The left hand side is just $((m_1 x^N + r_1) + (m_2 x^N + r_2)) \bmod P$. Each one of $x^k (x^{L_1} + x^{L_2}) \bmod P$ is also known.

Note also that each of those is a polynomial of degree smaller than $N$. These polynomials form a vector space over $\mathrm{GF}(2)$. If we think in terms of vector spaces, the problem now is to figure out a linear combination of the base vectors $x^k (x^{L_1} + x^{L_2}) \bmod P$ that gives $I (x^{L_1} + x^{L_2}) \bmod P$.

In other words, we need to solve a linear equation. That’s a job for our beloved Gauss-Jordan elimination. But this time we work in $\mathrm{GF}(2)$, so adding rows just means bitwise-xor, and there is no scaling involved.

In the rare chance that we don’t get a unique solution, i.e. the base vectors aren’t actually linear independent, we can pick another message with a different length try again.

If we go back to the real data we collected and pick these two messages:

m1, r1 = AAFF 0040 2EEC
m2, r2 = AAFF 040E02 0450

The lengths are $L_1 = 32$ and $L_2 = 40$, so the base vectors are (remember first bit is highest power):

k  | x^k (x^L1 + x^L2) mod P
---|-------------------------
0  | 0001 1011 1100 0010
1  | 0011 0111 1000 0100
2  | 0110 1111 0000 1000
3  | 1101 1110 0001 0000
4  | 1101 1100 0010 0101
5  | 1101 1000 0100 1111
6  | 1101 0000 1001 1011
7  | 1100 0001 0011 0011
8  | 1110 0010 0110 0011
9  | 1010 0100 1100 0011
10 | 0010 1001 1000 0011
11 | 0101 0011 0000 0110
12 | 1010 0110 0000 1100
13 | 0010 1100 0001 1101
14 | 0101 1000 0011 1010
15 | 1011 0000 0111 0100

Our target polynomial $((m_1 x^N + r_1) + (m_2 x^N + r_2)) \bmod P$ is 1101 0110 1110 0110, or:

$$x^{15} + x^{14} + x^{12} + x^{10} + x^{9} + x^{7} + x^{6} + x^{5} + x^{2} + x^{1}$$

Solving for $a_k$, and we get that every single $a_k$ is $1$, i.e. init is the all-ones 0xffff.

Solving for $F$

Now the only thing remaining to figure out is the final value $F$. Going back to this:

$$r \equiv m x^N + I x^L + F \pmod P$$

Solving for $F$ is pretty easy now, given that we know everything else:

$$F \equiv m x^N + r + I x^L \pmod P$$

In other words, we can do a CRC calculation on something we know, assuming that final is zero, and check the bitwise-xor with the real CRC to get the real value or final. In the case of this adjustable desk it turns out that final actually is just zero.

Now we have the complete set of parameters:

tap   = 0xa006
init  = 0xffff
final = 0x0000

This is not any standard CRC, as far as I know. I have no idea why the desk was programmed this way.

I tried this process on some other samples including some CRC-32 ones and it seems to work fairly reliably given like 10 example pairs.

Did you really do all these just to hack into a desk?

No, I just wrote a program that went through all $2^{16}$ values of tap, assuming that init = 0xffff and final = 0x0000 just like Modbus. I found tap = 0x2006 works.

Then they started talking about sending it into a solver like Z3 or something, in case brute force didn’t work (well, brute forcing 32-bit CRCs where you need to figure out both init and tap does seem to be intractable), but I was so sure that I can reverse engineer CRC without brute force or relying on solvers that I actually went ahead and did it. Got nerd snipped, I suppose.

This article assumes some familiarity with nix-lang. This is not a tutorial.

The syntax with A; E

Nix-lang has a construct with A; E. Its purpose is to bring the attributes of the attrset A into scope as variables within the expression E. So instead of:

[ pkgs.foo pkgs.bar pkgs.baz ]

You can write:

with pkgs; [ foo bar baz ]

As a syntax sugar, this has the obvious advantages of making code look shorter, and the obvious disadvantage of making it confusing.

‘The’ problem with with

A problem arises when there’s a conflict between a lexically bound variable (‘normal’ various bound by let or a lambda parameter) and something that’s bound by with:

let a = 4;
in with { a = 3; }; a

An obvious way to resolve this would be to make this expression evaluate to 3. This comes with a price though: Lexical scope would be broken. This is in fact the most commonly cited reason that an almost equivalent construct, with in JavaScript, is considered deprecated. (See MDN for example.)

Since we’re talking about Nix, let’s imagine that Nix-lang worked this way, with overriding normal variables. You have in your code:

let foobar = "something";
in with pkgs;
  /* ... */

And next month, a package called foobar is added to Nixpkgs. Your code would be broken.

Thankfully, that’s not what happens in nix-lang.

The solution in Nix-lang

In nix-lang, with does not override lexically bound variables. This example, in the real nix-lang, evaluates to 4:

let a = 4;
in with { a = 3; }; a

with simply never override something that’s lexically bound. with A; E only affects variables in E that are otherwise unbound.

A desugaring of with

This means that with in nix-lang is a purely syntactical construct. You can eliminate all uses of with in an expression without ever evaluating the code, because you don’t need to.

The only thing changed is that an unbound variable, which would be a syntax error, now becomes a reference to the attrset mentioned to with.

So, to desugar with, look at each variable mentioned in the code:

• If it’s lexically bound, leave it as is.
• Otherwise, if there are no with constructs above it, report an unbound variable.
• Otherwise, take all the with A; that wraps this variable, combine them together like (A1 // A2 // A3), and change the variable v into ((A1 // A2 // A3).v)

Some examples:

• Most common usage: Just let me type less stuff:

  # Before
  [ pkgs.foo pkgs.bar pkgs.baz ]
  
  # After
  with pkgs; [ foo bar baz ]

• Lexical scoping is preserved

  # Before
  let a = 4;
  in with { a = 3; b = 4; c = 5; }; a + b + c
  
  # After
  let a = 4;
  in a + ({ a = 3; b = 4; }.b) + ({ a = 3; b = 4; }.c)

Well technically…

There’s a small mistake with the translation above. You can’t just copy verbatim the attrset used in with into each usage, because the with dictionary is only evaluated once. This hardly matters ever, but ideally, the latter example should be translated into something like: (Where __with_1 is a fresh variable)

let a = 4;
in let __with_1 = { a = 3; b = 4; c = 5; };
  in a + __with_1.b + __with_1.c

Imagine that instead of { a = 3; b = 4; c = 5; } there is a complicated computation. The naive translation would duplicate this computation, which is probably undesirable. This case occurs in the commonly used pattern:

with (import <nixpkgs> {}); /* ... */

So should we use with?

Be careful. The fact that with modifies the behavior of unbound variables instead of all variables is arguably an improvement over the now deprecated JavaScript with. But it still modifies the behavior of unbound variables.

Given the possibly confusing behavior, I personally only use with in certain circumstances in which I’m familiar with the consequences, like:

environment.systemPackages = with pkgs; [ foo bar baz ];

meta = with lib; { /* ... */ };

helperFunction = with builtins; /* use builtins here */

I don’t really like with (import <nixpkgs> {});, but admittedly, I sometimes get sloppy and use it.

Hopefully, equipped with a better understanding of what nix-lang’s with does, you know what you want to do with it.

I probably already annoyed you with all those with jokes. I’m going to stop.

一次命运转折的约饭

2020 年秋季开学之前的什么时候，在一次约饭的时候，正好和一些计算机系专业课的助教说到这学期要参加的一些课程的事情。

根据课程的安排（可参见也谈课改——以网原为例一文），两门比较硬核的专业课：计算机组成原理和计算机网络原理（简称计原和网原而不是什么乱七八糟的东西）作为两门实验项目改动比较大的专业课，现在大概是如下的情况：

• 从 2020 年开始，计原课程的“奋战三星期，造台计算机”与国际先进技术接轨，又原来的 MIPS 架构改为 RISC-V 架构。当然造机这件事是不变的，三人一组做一个软核。这里有两个小故事：
  • 之前假期的时候在 ICFP 的时候在神秘的 Coffee break room 聊的时候，有人就提到 MIPS 架构已经凉了。虽然还能买到 MIPS 的芯片和产品，但是已经不再有新的发展了。
  • 有一位同学在上课之前尝试翻了下往年题目，发现了关于分支延迟槽的问题，于是在群里问这个可以在哪儿学到。这位同学可能需要一个时光机。
• 从 2019 年开始，网原课程的大实验是自己造路由器，分为软件实验和硬件实验两个 track。2020 年的具体情况如下：
  • 软件实验是每组 3 位同学，每人做一个路由器，然后测试时使用在线平台的 Raspberry Pi 运行，通过交换机的虚拟连接测试在给定网络拓扑下的性能和功能。
  • 硬件实验是每组 3 位同学，一起做一个路由器。今年的要求是在一个 FPGA 上完成大部分转发相关的内容，然后在计原实验里造的软核 CPU 上运行 RIPv2 动态路由协议相关的处理，也就是说相当于三个人一起做了两个课的实验，当然要求显然是高于软件实验的。因为包含了计原和网原两个课的内容，所以被称为“计网联合实验”。

其中一位助教建议我参加联合实验。考虑到我之前并没有参加前面的硬件相关的数字逻辑课程，我一再说这可能是误解了我的水平，但是看来这位助教对我还是很有信心的。

后来和找到的两位朋友 akyuu 和 pwe 组成了小组，说了这些事情之后，我们按照课程要求报了名，通过一个（看来比较主观但并不是没有道理的）“选拔”，正式加入了联合实验的队伍。

摸鱼和赶工的几周

联合实验是每周的一个晚上开一次会，讨论上周的工作，布置下周的任务。佛系的我们最开始是每周大概约一个研讨间待上个好久，后来直接在宿舍的活动室工作了。

由于摸鱼比较严重，我们经常是赶在晚上开会当天才做完，最神奇的一次是从研讨间出来之后，已经还有大概只半个小时左右就要开会了，只能飞奔赶往。

暂时先不说技术细节了，感觉没什么特别的，可能以后再讲吧。

感觉在造机之前的那段时间里，其实是最开始的时候做那些比较基础的功能的时候比较头疼，因为确实没有做过什么硬件和网络相关的东西，需要熟悉整个流程、AXI Stream 协议，一些 workflow 相关的事情等，以及做出来的东西的可见性较差，不太能直观感受到进度。

在我们完成转发引擎的那个晚上，我提议跑一个 HTTP 服务器通过我们的 FPGA 路由下载一个文件。当我们看到 python3 -m http.server 的页面，以及成功下载了一个文件的时候，至少我当时非常高兴，感觉到自己至少做了一个可以在一定程度上接入现有的环境中作为 infrastructure 的一个东西。

或者简单来说就是，它通了。

那天晚上在宿舍活动室，我们组的三人对着一个 effectively 就是一根超级贵的网线的板子，庆祝了好久。

当然，我们也有不太顺利的时候。中间有一段时间，我们发现转发部分的逻辑有性能问题，十分困惑，改的时候也很头疼，越改性能越差，改着改着干脆就不通了。试了很多种方式才最终搞定。

造机的三周

硬件实验，造机还是得造的。

在硬件的设计方面，我们做的是一个 Classic RISC pipeline 的五级流水线设计，这点上没有什么特别的。在具体的一些细节上实际上参考了之前路由器的数据处理流水线，以及喵喵的一些建议，没有按照传统的方式设计控制器，而是使用 ready/valid 握手和总线仲裁协调各个流水线级的工作。在之后的一些调整设计、修改实现的过程中，虽然不是很明显，但是还是能感受到这样的一个设计所带来的方便，因此我觉得这是一个比较科学的做法。

总线我们使用了一个相当于 Wishbone Classic 的总线协议，当然没有使用现有的组件，而是自己实现了访存、外设、仲裁、互联的模块。本来最开始想做的是 Pipelined 模式的总线，但是实在是没做出来就放弃了。在总线相关的事情上，我也在和一些课程的编外人员（“不是助教”）讨论，要不要在硬件相关的实验中加入总线协议的内容，使大家的设计可以互联互通。

不知道是不是 Stolkhome Syndrome 的原因，我现在真的非常喜欢 RISC-V 的指令集。

如果更客观的来说，我之前曾经也想过自己做一个 CPU。之前我曾经做过一个 6502 的模拟器，可以运行一个简单的 BASIC 解释器；也尝试用 Clash 做过一些神秘的小指令集的 CPU，但是由于设计方面实在是不知道如何下手最终搁置了。

而 RISC-V 实际上是一个美妙的机会，三周实现的 RISC-V RV32I 的大部分指令，实际上相当于已经是一个 riscv32-none 的裸机，可以使用现有的工具链。RISC-V 的活跃的社区意味着这些工具不是祖传的 legacy，而是最新的成果。

或许这就是开放的社区的意义所在吧。

意外顺利的又几周

当然，说是意外顺利，可能更恰当的说法是有些意外，有些顺利。

CPU 与路由器的集(feng)成(he)从把 CPU 的总线和基于 AXI Stream 的数据平面连接开始。在这点上折腾了很久都没搞定，最后发现是别的地方写出锅了。之后逐渐的我们把路由部分的逻辑中需要软件访问的部分，以及收发以太网帧的都作为 MMIO 接入到了总线上。

队友也参考提供好的模板完成了 RIP 协议的软件，在本地测试了一下，看起来可以和 BIRD 互操作。

（有一次聊天的时候意外发现，VGA 用的 framebuffer 直接复制过来就是以太网 framebuffer，名字都不用改。）

这段时间我的状态也不是很好，主要还是靠两位队友 carry 的大部分硬件工作和全部软件工作，作为组长的 dram 就一直在划水。这里我要真诚感谢一下队友，感谢一下助教和不是助教，也要感谢此时以及支持我的所有人。

验收工作

随着千兆网络测速仪的研制成功，我们还是发现了一些大大小小的 bug，但是修起来还不是那么难。有两个到现在也没太搞明白的问题，一个是软件部分有一段似乎不太能正常运行，需要加上一些没用的代码，另一块是软件接收到的以太网帧出现被截断的问题，在换了一些写法之后似乎没有再遇到相同的现象，所以也没有追究。

到最后验收还是花了不少时间，不过比较高兴的是，最终测试环境的各种网络拓扑下的路由器工作都比较顺利。其中有一个测试是将三个路由器接成一个环，然后移除其中两个路由器之间的链路，过一段时间再恢复链路，来测试 RIP 动态路由协议的工作状况。由于之前说到我一直在划水，其实我是不知道软件是个什么情况的。连软件担当的队友都表示没想到写的东西能正常完成错误恢复。

验收完成之后，我三人一起去吃了一顿烤肉。

造机的答辩

2020 年 12 月 19 号是造机的答辩，作为第 5 组，在别的组答辩的时候，我们组的群里依次出现了 v3 到 v10 的 slides，页数从 25 增长到了 31。

答辩的整体过程都是我在说，不知道是紧张还是怕 31 页 10 分钟时间不够的原因，我的语速特别快。

答辩的全程好像有人来录像，以及听说有造机队伍来采访了某位队友。看来这些写新闻的对造机的工作不是很了解吧，至少我觉得最后写出来的推送并没有展现出我们实际完成了什么工作，从评论区也可以看出来大家没太理解我们在做什么。评论区有一个家长自称孩子 11 岁，想找个指导老师做一下这个三周造机之类的。倒不一定是技术难度问题，给这年纪孩子做点什么不好，来造机干啥……

另外，在答辩的最后，我插播了一段私货。事实上，这段私货的内容是我前一天的晚上才准备好的，当时事实上紧急叫了几个朋友帮忙看看有没有什么写的不太妙的地方，做了一些细微修改。这段在演讲的时候，内容我自己有所发挥，但是大致的文字内容是前一天写好的，在此：

Claire Wolf 是 RISC-V B 扩展指令规范的主编，我们每个组的三个扩展指令就选自这里。她除此之外对开源的数字逻辑工具有很大贡献，包括开源的 HDL 工具 Yosys 等。

大家可能注意到我们下发的 bitmanip 规范的待定稿的作者的名字写的是 Clifford Wolf。如果大家有关注过这个人的话，就会知道这位 RISC-V 社区的重量级人物是一位跨性别者，在去年的大概这个时候正式以女性的身份出现在大家面前，包括将自己的名字改为 Claire。

我本人至少是非常敬佩她的。我想起不记得在哪里看到的一句话：RISC-V 给大家一个公平的起跑线。我希望这个公平的起跑线，不仅在技术上给大家一个开放的环境，不被当前 CPU 核心设计领域当前的近乎垄断的现状限制住，而且能让我们这些搞科技和学术的不被那些无关的事情所困扰，能够真正展现出自己的水平。

近来发生的一些跨性别者受到不正当对待事情，大家可能已经听说过了。我其实一直比较愧疚，没有做什么事情来给予帮助。希望今天我所说的至少能引起大家对这些群体以及这些事件的一些关注和思考。我觉得对于大部分人来说，尽量去理解，就已经是很好地在支持了。

结束之后，一位助教指出，网络测试仪在两个 FPGA 之间通信所使用的协议 PonyLink 也是 Claire Wolf 的作品。大部分人可能并不能理解这样一个身份所带来的痛苦，但是至少我们作为技术人员，能够谈论的是一个人所做的贡献，而不是一些无关的处境或者身份问题，这其实正是我想看到的。

最终答辩

最终的答辩计划在 2021 年 1 月 12 号进行，那时可能会进行组间的联通测试。

上午是，见到了很多助教和上一届联合实验的同学，聊了很多有趣的事情和无聊的事情。

下午的测试非常迷惑，各种问题，可以参见助教 twd2 的博客。

某网络专家对此评价为“群魔乱舞”。

The problem statement

On a grid with width $m$ and height $n$, how many triangles have lattice points as vertices but otherwise have no lattice points on the edges and interiors? (Such triangles are called ‘empty’.) Find the answer modulo $10^9 + 7$.

For example, for $m = 1$ and $n = 2$, the $12$ empty triangles by shape and multiplicity are given below: (Image from kata description.)

Geometry part

According to Pick’s theorem, a triangle with lattice point vertices has area: $$A =i + \frac{e}{2} + \frac{1}{2}$$ Where $i$ is the number of lattice points on the interior (not counting edges), and $e$ is the number of points on the edges (not counting vertices). Therefore triangle is empty iff its area is $1/2$ and its vertices are lattice points. (For the sake of brevity we always work with lattice points from now on.)

Intuitively, empty triangles have a relatively ‘thin’ shape. The longer edges get, the ‘thinner’ the triangle gets. An exact useful bound in the ‘thickness’ of an empty triangle be encapsulated in this lemma:

Lemma: For an empty triangle, two of its vertices coincide with opposite corners of its bounding box.

Proof: Pick the leftmost point $A$ and rightmost point $B$ of a triangle. (If there is a tie, pick an arbitrary one.)

Without loss of generality, we assume that $B$ is higher than or level with $A$, and $C$ is above the line segment $AB$. Construct a vertical line through $C$, intersecting $AB$ at $D$ as shown. Let $h = \left|CD\right|$ and let $m$ be the horizontal distance between $A$ and $B$. Then the area of $\triangle ABC$ is $hm/2$. This can be shown by constructing a horizontal line through $D$ intersecting the bounding box on the side of $A$ at $E$, and on the side of $B$ at $F$, then $\triangle CDE = \triangle CDA$ and $\triangle CDF = \triangle CDB$. Then:

$$\begin{split} \triangle ABC &= \triangle CDA + \triangle CDB \\ &= \triangle CDE + \triangle CDF \\ &= \triangle CEF \\ &= hm/2 \end{split}$$

(Where clear from context $\triangle XYZ$ represents the triangle’s area)

Therefore if $\triangle ABC$ is empty, then $hm = 1$. If $C$ is within the rectangle with $A$ and $B$ as corners (including boundaries), then it satisfies the desired conclusion.

Otherwise $C$ is above $B$, and since they are lattice points, $C$ must be at least $1$ unit higher than $B$, therefore $h \ge 1$. But we already have $m \ge 1$, so it must be the case that $h = m = 1$. Then one of $CA$ and $CB$ is vertical.

• If $CA$ is vertical, then $\left|CA\right| = h = 1$. We are now constrained in a $1 \times 1$ box, in which the only possible triangle shape of edge lengths $(1, 1, \sqrt{2})$ indeed has two vertices as corners of its bounding box.
• If $CB$ is vertical, then $A$ and $C$ are corners of the bounding box of $\triangle ABC$

Thus concludes the proof of this lemma.

Now we only need to find, for each possible bounding box size, the number of empty triangles that fits exactly into this bounding box. There are four completely symmetric ways to fit an empty triangle into its, depending which diagonal the triangle’s two points ‘outer’ points sit on, and on which side the third ‘inner’ point lies. Here’s the four cases illustrated, where in each case the shown diagonal is one edge of the triangle, and the other vertex is in the shaded region.

Therefore we can just calculate one case and multiply the answer by four. Let’s put one case at the origin like this:

Supposed the rectangle has width $m$ and height $n$. Similar to what has been shown while proving the lemma, for the area of $\triangle ABC$ to be $1/2$, $C$ must lie on a line that is $AB$ shifted down by $1/m$, and it must also be a lattice point. The equation of line $AB$ is: $$\frac{x}{m} + \frac{y}{n} = 1$$ And therefore that of the shifted line is: $$\begin{align} \frac{x}{m} + \frac{y + 1/m}{n} &= 1 \\ nx + my + 1 &= mn \\ m(n - y) + n(- x) &= 1 \end{align}$$ Bézout’s identity tells us that there are solutions if and only if $\gcd(m, n) = 1$. We are interested in only solutions in the region $0 \le x < m$ and $0 \le y < n$. Given one solution $(x=x_{0},y=y_{0})$, the general solution is $(x = x_0 + km,y = y_0 - kn)$ where $k$ is any integer. There is a unique solution $(x = x_0 + \lfloor y_0 / n \rfloor m, y = y_0 \bmod n)$ that lies within the region. This can be shown first by noting that euclidean division of integers gives a unique $0 \le y < n$ such that for some integer $k$, $y_0 = kn+y$. Then we verify that $x \ge 0$, which shows that the solution is inside the region we want:

$$\begin{split} x &= x_0 + \lfloor \frac{y_0}{n} \rfloor m \\ &= \frac{m(n - y_0) - 1}{n} + \lfloor \frac{y_0}{n} \rfloor m \\ &= m(1 + \lfloor \frac{y_0}{n} \rfloor - \frac{y_0}{n}) - \frac{1}{n} \\ &\ge m \cdot \frac{1}{n} - \frac{1}{n} \\ &= \frac{m - 1}{n} \\ &\ge 0 \end{split}$$ (In the middle inequality step, note that since $y_0$ is a integer, $y_0 / n$ is some integer plus $k / n$, where $k$ is a integer such that $0 \le k < n$.)

Therefore an $m \times n$ bounding box has four empty triangles if $\gcd(m, n) = 1$, and none otherwise.

We however need to consider all bounding box sizes from $1 \times 1$ up to $m \times n$, instead of just one size. A size $j \times i$ rectangle fits into a size $m \times n$ rectangle $(n + 1 - i)(m + 1 - j)$ times. So the answer is: $$4\sum_{i = 1}^{n} \sum_{j = 1}^{m} [\gcd(i, j) = 1] (n + 1 - i) (m + 1 - j)$$

($[P]$ is the Iverson bracket, which is $1$ when $P$ is true and $0$ otherwise.)

(Note 1: I’m doing this weird transposition of coordinate thing (just once here) because we don’t use coordinates consistently between geometry and, shall we say, discrete mathematics. In geometry to refer to a point we have $x$ before $y$, and $y$ positive goes up, but if we refer to an entry in a matrix we have row number before column number, and successive rows goes down. Things are completely symmetric anyway, so the best way to deal with this inconsistency is to forget that you noticed it or that I told you it.)

(Note 2: This function without the factor $4$ can be found as A114999 on OEIS.)

Current progress: We know that we need to find $4 \times a(n, m)$ where $$a(n, m) = \sum_{i = 1}^{n} \sum_{j = 1}^{m} [\gcd(i, j) = 1] (n + 1 - i) (m + 1 - j)$$

Number theory part

$$\begin{split} a(n, m) &= \sum_{i = 1}^{n} \sum_{j = 1}^{m} [\gcd(i, j) = 1] (n + 1 - i) (m + 1 - j) \\ &= \sum_{i = 1}^{n} \sum_{j = 1}^{m} [\gcd(i, j) = 1] ((n + 1) (m + 1) - (m + 1) i - (n + 1) j + ij) \\ \end{split}$$

Möbius inversion is an application of the inclusion-exclusion principle. A function is defined as follows:

$$\mu(n) = \begin{cases} (-1)^{k} & \text{if $n$ factorizes to $k$ distinct primes} \\ 0 & \text{otherwise} \end{cases}$$ This function has this important property: $$\sum_{d | n} \mu(d)=[n=1]$$ (Where $d|n$ means for each positive divisor of $n$ including $1$ and $n$, of course not counting twice if $n$ is $1$.)

We can use this equation to replace $[\gcd(i, j) = 1]$ with $\sum_{d|\!\gcd(i, j)} \mu(d)$, which allows us to ‘unleash’ the properties of $\gcd(i, j)$, namely that the set of divisors of $\gcd(i, j)$ is the set of common divisors of $i$ and $j$ (which I write as summing over $d | i, d | j$ below), which in turn allows us to rewrite out summations: $$\begin{split} \cdots &= \sum_{i = 1}^{n} \sum_{j = 1}^{m} \sum_{d | \!\gcd(i, j)} \mu(d) ((n + 1) (m + 1) - (m + 1) i - (n + 1) j + ij) \\ &= \sum_{i = 1}^{n} \sum_{j = 1}^{m} \sum_{d | i, d | j} \mu(d) ((n + 1) (m + 1) - (m + 1) i - (n + 1) j + ij) \\ &= \sum_{d = 1}^{\min\{n, m\}} \sum_{i = 1}^{\lfloor n / d \rfloor} \sum_{j = 1}^{\lfloor m / d \rfloor} \mu(d) ((n + 1) (m + 1) - (m + 1) di - (n + 1) dj + d^2ij) \\ \end{split}$$

Note that in the last step I ‘switched variables’ $i \leftarrow i/d$ and $j \leftarrow j/d$, and instead of looking for possible $d$ given $i$ and $j$, I look for possible $di$ and $dj$ given $d$, which is simpler because it does not involve a divisibility check.

Let’s split that up into three parts for easier handling later on:

$$\cdots = a_0(n, m) + a_1(n, m) + a_2(n, m)$$

Where:

Where $\mathsf{ID}(n)$ is the sum of $\mathsf{id}(n) = n$, that is $\mathsf{ID}(n) = n (n + 1) / 2$.

The three parts have a common pattern: $$\begin{align} s_{k, u}(n, m) &= \sum_{d = 1}^{\min\{n, m\}} \mu(d) d^k u(\lfloor \frac{n}{d} \rfloor, \lfloor \frac{m}{d} \rfloor) \end{align}$$ Where $u$ is trivially computable. If we figure out how to compute $s_{k, u}$, we’re set.

Intermission: Number-theoretic summation trick

Now for something completely out of nowhere.

The Dirichlet convolution of two functions is defined as: $$(f * g)(n) = \sum_{d | n} f(d) g(\frac{n}{d})$$ Let $G(n) = \sum_{i = 1}^{n} g(i)$, and similarly let capital letter functions represent the sum of the corresponding lowercase letter functions. An observation is that if we sum a Dirichlet convolution, we get: (The sum over $cd = i$ means all positive integers $c$ and $d$ such that $cd = i$, and the sum over $cd \le n$ works similarly) $$\begin{split} \sum_{i = 1}^{n} (f * g)(i) &= \sum_{i = 1}^{n} \sum_{d | i} f(d) g(\frac{i}{d}) \\ &= \sum_{i = 1}^{n} \sum_{cd = i} f(c) g(d) \\ &= \sum_{cd \le n} f(c) g(d) \\ &= \sum_{c = 1}^{n} f(c) \sum_{i = 1}^{\lfloor n / c \rfloor} g(i) \\ &= \sum_{c = 1}^{n} f(c) G(\lfloor \frac{n}{c} \rfloor) \end{split}$$ Isolating the first term gives: $$f(1) G(n) = \sum_{i = 1}^{n} (f * g)(i) - \sum_{c = 1}^{n} f(c) G(\lfloor \frac{n}{c} \rfloor)$$ If $f(1) \ne$ 0, then: $$G(n) = \frac{1}{f(1)} \left(\sum_{i = 1}^{n} (f * g)(i) - \sum_{c = 1}^{n} f(c) G(\lfloor \frac{n}{c} \rfloor) \right)$$ Assume for now that $f$ is chosen such that $F(i)$ and $\sum_{i = 1}^{n} (f * g)(i)$ are efficiently computable, either directly via an $O(1)$ formula or indirectly via a ‘recursive’ application of this technique.

Note that $\lfloor n / c \rfloor$ can only take on a maximum of about $2 \sqrt{n}$ values:

• $n/1, n/2,\dots,n/\sqrt{n}$ (final term is approximate), for $c \le \sqrt{n}$
• about $\sqrt{n}, \sqrt{n} - 1, \dots, 1$, for $c > \sqrt{n}$

The sum over $c$ from $1$ to $n$ is now broken up into $O(\sqrt{n})$ segments where $\lfloor n / c \rfloor$ is equal, and $G(\lfloor n / c \rfloor)$ only needs to be calculated once per segment.

Given $x$, we want to solve for $j$ in $\lfloor n / j \rfloor = x$, which shall give us the form of each segment.

$$\begin{gather} x = \lfloor \frac{n}{j} \rfloor \\ x \le \frac{n}{j} < x + 1 \\ \frac{n}{x+1} < j \le \frac{n}{x} \\ \left\lfloor \frac{n}{x+1} \right\rfloor + 1 \le j \le \left\lfloor \frac{n}{x} \right\rfloor \end{gather}$$

Therefore given the the first interval’s starting point $l_{1} = 2$, the end of this interval is $r_{1} = \lfloor n / \lfloor n / 2 \rfloor \rfloor$, and then the next interval starts at $l_{2} = r_{1} + 1$ and ends at $r_2 = \lfloor n / \lfloor n / l_{2} \rfloor \rfloor$, etc. until $n$ is reached. In each interval $[l_i, r_i]$ the sum is $(F(r_i) - F(l_i)) G(\lfloor n / l_i \rfloor)$.

By recursively computing $G$ as shown, memoizing using a hash table, we can achieve $O(n^{3/4})$ time complexity and $O(n^{1/2})$ space complexity. If we use a sieve to pre-compute the first $O(n^{2/3})$ terms of $G(n)$ we can achieve $O(n^{2/3})$ time and space complexity.

The complexity proof: In the no-precomputation case every $G(\lfloor n / d \rfloor)$ is computed exactly once, each taking $O(\sqrt{\lfloor n / d \rfloor})$ time. As discussed earlier $\lfloor n / d \rfloor$ takes on the values $1, 2, \dots, \sqrt{n}$ and $n/1, n/2, ..., n/\sqrt{n}$ (We are talking asymptotics here so we’ll just ignore the details.), therefore the total time is: $$\begin{align} T(n) &= \sum_{i = 1}^{\sqrt{n}} O\left( \sqrt{i} + \sqrt{\frac{n}{i}} \right) \\ &= \sum_{i = 1}^{\sqrt{n}} O\left( i^{1/2} + i^{-1/2} \sqrt{n} \right) \\ &= O((\sqrt{n})^{3/2}) + O((\sqrt{n})^{1/2}) \sqrt{n} \\ &= O(n^{3/4}) \end{align}$$ If we can find the first $O(n^k)$ (where $1/2 \le k \le 3/4$) values of $g$ in $O(n^k)$ time we can accelerate the process. This is often possible for, for example, multiplicative functions where Euler’s sieve can be used. For more detailed information check this note on Codeforces. The new execution time is

$$\begin{align} T'_k(n) &= O(n^k) + \sum_{i = 1}^{n^{1 - k}} O(\sqrt{\frac{n}{i}}) \\ &= O(n^k + n^{(1 - k) / 2} \sqrt{n}) \\ &= O(n^k + n^{(2 - k) / 2}) \end{align}$$

Asymptotically, $T'_k(n)$ is minimized when $k = (2 - k) / 2$, which is $k = 2/3$. In practice, the number of values to precompute is a tunable that will be set according to needs.

To summarize, this means that if $h = f * g$, and $H$ and $F$ can be computed efficiently either directly or ‘recursively’ by this technique, then $G$ can be computed efficiently.

I could not find any authoritative reference on this method. The best I could find is this answer on math.SE.

The algorithm described above is often shown as a method to compute isolated values of $G(n)$, but it actually computes $G(\lfloor n / d \rfloor)$ for all possible values of $\lfloor n / d \rfloor$. This will become handy if, as alluded to earlier, $F(n)$ is still non-trivial but this method can apply, but we won’t need this for now. We shall see how this helps us here in a minute, but first we need to find $f$ and $h$.

Back to business

In the definition of $s_{k,f}$, we extract the ‘difficult’ part $\mu(n) n^{k}$ and we can define another function along with it: $$\begin{align}m_k(n) &= \mu(n) n^k \\\mathsf{id}^k(n) &= n^k\end{align}$$ The Dirichlet convolution of the two is: $$\begin{align}(m_{k} * \mathsf{id}^{k})(n) &= \sum_{d|n} \mu(d) d^k (\frac{n}{d})^k \\&= \sum_{d|n} \mu(d) n^k \\&= (\sum_{d|n} \mu(d)) n^k \\&= [n = 1] n^k \\&= [n = 1]\end{align}$$ That’s quite simple. This is no surprise, since $[n = 1]$ is the identity of Dirichlet convolution, and $m_{k}$ is the Dirichlet inverse of $\mathsf{id}^{k}$. Refer to Wikipedia for details.

Can we use the earlier technique to compute sums of $m_k(n) = \mu(n) n^k$? The answer is yes, as the sum of the functions involved are either trivial or well-known: $$\begin{align} \sum_{i = 1}^{n} [i = 1] &= 1 \\ \sum_{i = 1}^{n} 1 &= n \\ \sum_{i = 1}^{n} i &= \frac{i (i + 1)}{2} \\ \sum_{i = 1}^{n} i^2 &= \frac{i (i + 1) (2i + 1)}{6} \\ \end{align}$$ Therefore it is possible to compute $M_k(\lfloor n / d \rfloor)$ for all possible values of $\lfloor n / d \rfloor$ in $O(n^{3/4})$ time. (Remember that uppercase means sum.)

Can we use the faster $O(n^{2/3})$ method? The answer is yes because $m_k$ is multiplicative. I’ll refer to the notes on Euler’s sieve mentioned earlier.

Remind you, we want to compute this. $$\begin{align} s_{k, u}(n, m) &= \sum_{d = 1}^{\min\{n, m\}} m_k(d) u(\lfloor \frac{n}{d} \rfloor, \lfloor \frac{m}{d} \rfloor) \end{align}$$ This is eerily familiar. In fact this is almost what we did in the intermission, but now $u$ takes two arguments.

How many values can the pair $(\lfloor n / d \rfloor, \lfloor m / d \rfloor)$ take on? As $d$ increases, $\lfloor n / d \rfloor$ decreases, and it will take about $2 \sqrt{n}$ steps doing so, and similarly for $\lfloor n / d \rfloor$, therefore $(\lfloor n / d \rfloor, \lfloor m / d \rfloor)$ takes on a maximum of about $2 (\sqrt{n} + \sqrt{m})$ steps (not a simple sum because the steps can overlap). For example for $n = 10$ and $m = 3$, the combined steps like this (open the image in a new tab if it’s too small for you):

Apply the exact same strategy as before: For the first interval, the start is $l_1 = 1$, and end is $r_1 = \min\{\lfloor n / \lfloor n / l_1 \rfloor \rfloor, \lfloor m / \lfloor m / l_1 \rfloor \rfloor\}$, then for the second interval $l_2 = r_1 + 1$ and $r_2 = \min\{\lfloor n / \lfloor n / l_2 \rfloor \rfloor, \lfloor m / \lfloor m / l_2 \rfloor \rfloor\}$ and so on until $\min\{n, m\}$. The sum in each interval is then $(M_k(r_i) - M_k(l_i - 1))f(\lfloor n / l_i \rfloor, \lfloor m / l_i \rfloor)$.

We can see that each $r_i$ and $l_i - 1$ is either of the form $\lfloor n / d \rfloor$ or $\lfloor m / d \rfloor$ or $0$. For the algorithm to work, $M_k(0)$ should be the natural choice of sum of no numbers, $0$. Therefore if we compute all $M_k(\lfloor n / d \rfloor)$ and $M_k(\lfloor m / d \rfloor)$ in $O(\max\{n, m\}^{2/3})$ time, we can use $O(\sqrt{n})$ time to combine them into our answer $s_{k, f}(n, m)$ (provided that $f$ is available in $O(1)$, which is the case.)