ZpqrtBnk

And to 18

sgay@pilotine.com — Tue, 14 Jul 2026 12:00:00 Z

Having just upgraded this site to Umbraco 17, it seemed right to finish the work and go to 18.

The actual update is straighforward. NuGet-update packages, deal with a few obsoleted methods that need to be removed, refactor an UmbracoApiController. Less than 30 minutes of work.

Reboot... and we are now on 18!

Time to monitor the application and check that everything works.

Since I am currently working with Datadog, I have access to their dogfooding program. And thus, the Docker platform that hosts this site is fully instrumented. So... this is what we are going to use.

DISCLAIMER: I work with them, I like it there, I may be biased, etc. And also the dogfooding program comes free, which helps.

Datadog Agent

The dashboard complains that I run an old version of the agent and should upgrade. Since the agent itself runs on Docker, that is a quick docker-compose operation (dc is my alias for docker compose):

dc pull
dc down dd-agent
dc up dd-agent -d

Disks

Next, the monitors I have defined warn me that my disk space is getting low.

Weird enough, it seems that my small /dev/sda1 root partition is filling up, while my huge /dev/sda2 partition, specifically dedicated to Docker (mounted as /var/lib/docker), is idle.

A quick search reveals this has been reported before and is a matter of containerd writing to the wrong FS. Edit /etc/containerd/config.toml to specify root = "/var/lib/docker/containerd", stop Docker, reboot machine, restart all containers, cleanup, fixed.

Monitors are back to green:

Memory

Now, this is what I was impatient to see. For reasons, I have a large (10K) number of not-so-small documents in this system, that of course I should delete, but for the sake of the argument, let us say I have to keep them.

Previously, the container would eat up about 2GB on startup. Expensive. But these documents are practically never ever touched. Woot, the container is now using around 256MB and remains stable. The new Umbraco hybrid cache is doing wonders here! Massive win!

At times though... the memory does jump up to 2GB. It just happens, and I do not know why. I need to monitor the situation, so I am going to define a new monitor on the container's memory usage. There. Now I will receive an email in case we cross the 1GB threshold.

HTTPS

And then... I cannot access the backoffice anymore. Back to this:

error:invalid_request
error_description:This server only accepts HTTPS requests.
error_uri:https://documentation.openiddict.com/errors/ID2083

But the front website works. Now if I try to enable headers forwarding in NGINX, this is replaced by a plain 400 error, both on back-office and front websites.

You will find many pages about this issue, but that one was really helpful. I finally got it to work with only these two forwarded headers in NGINX:

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;

And this in Program.cs:

builder.Services.Configure(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor |
        ForwardedHeaders.XForwardedProto |
        ForwardedHeaders.XForwardedHost;

    // docker network is 172.0.0.0/8
    options.KnownIPNetworks.Add(new System.Net.IPNetwork(System.Net.IPAddress.Parse("172.0.0.0"), 8));
});

And of course .UseForwardedHeaders() on the application.

Now it works, and I understand why, which is always better.

Memory (again)

Sure enough, I did get the email about the memory growing too big. Look at this:

Memory was stable and then it bumped to 2+GB. It went back down when I asked Docker Compose to restart the container. Now what happened that would cause the memory to go up like this? This: I deployed a new version of the container.

FWIW here is what the monitor reports:

It sure is pretty nice but does not explain why

Restarting the container is fine
Recreating the container is not

Looking at the filesystems, it definitively look like Examine rebuilds it entire indexes on restart, thus loading all content. But why?

Spoiler: I asked Claude.

And Claude told me that the issue was that Docker container have a randomly assigned hostname, which means Umbraco could not verify the state of this instance by checking its database tables, and thus performed a "cold boot", and thus rebuilt indexes.

Adding a hostname: whatever in the Docker Compose configuration file was all that was needed. Now the website container retains its hostname even when re-created and I can confirm memory stays low. Always.

What else on the Radar? Another DB! MSSQL is amazing, but has this constraint that it wants to use a minimum of 2GB of memory no matter what. This is a lot (and expensive). There have been a few efforts at providing a data layer for Postgres recently, and Claude can probably help us here. I will follow conversations and experiment as soon as possible.

And before we close this post, I cannot resist a bit of teasing. Thanks to the Datadog agent, all my logs are pushed to a central place. These are my Umbraco logs:

But of course I also have my other websites, or MSSQL, or MySql, or Forgejo logs here, as well as metrics about the CPUs and disks of my containers, network traffic, SQL queries/s...

Umbraco 13 to 17

sgay@pilotine.com — Sun, 12 Jul 2026 20:00:00 Z

This site has started as an Umbraco v4.x site, and has been regularly upgraded since then, never completely rebuilt. It has been running Umbraco 13 for about 3 years now, and it is about time to upgrade. We started with 17 in mind, so this post is about upgrading to 17. But 18 is out, and we are going to upgrade to it soon.

Packages

This is the easy part. The solution contains two projects: a Core project, and a UI project. Open each .csproj file, bump TargetFramework from net8.0 to net10.0, bump Umbraco package references from 13.0.2 to 17.4.0, bump a few other packages as per NuGet's suggestions.

The excellent Breaking Changes documentation tells us to remove RazorCompileOnBuild and RazorCompileOnPublish so, let us do it. It also tells us to clean our Program class a little. Remove a .AddDeliveryApi() call, remove a .UserInstallerEndpoints() calls, that is it.

At this point, rebuilding fails.

ModelsBuilderSettings.ModelsMode used to be an enum, looks like it is now a string. Quite simple to fix. Everything that queried the IPublishedContentCache does not compile anymore, porting to IPublishedContentQuery is trivial. There is no IContentService.SaveAndPublish() anymore, apparently, and one needs to Save() then Publish().

All in all, nothing dramatic.

Some of my custom Markdown property editor and converter will not compile, I am going to comment them out for the time being. And... it builds. Will it boot?

Database

Trying to boot the site fails... with a BootFailedException. A migration seems to want to delete a non-existing constraint named DF_umbracoUser_createDate. A quick Internet search shows that this happened to others as well, so something must have gone wrong with migrations at some point. Not going to troubleshoot, manually creating the missing constraints before upgrading is quicker:

 ALTER TABLE umbracoUser ADD CONSTRAINT DF_umbracoUser_createDate DEFAULT GETUTCDATE() FOR createDate;
 ALTER TABLE umbracoUser ADD CONSTRAINT DF_umbracoUser_updateDate  DEFAULT GETUTCDATE() FOR updateDate;

And presto... the site upgrades, boots, and I can log into the back-office.

Networking

At least, I can on my development machine, where I access Umbraco directly on localhost via IIS. But on production, where Umbraco runs in a Docker container behind NGINX, I get weird 400 Bad Request errors. At this point I went through a few hours of frustration and random experiments.

I sort of thought that it might have to do with forwarded headers as my issue was close to this Umbraco forum post. I added the ForwardedHeaders middleware to the app, along with the headers in NGINX configuration. Would not work. Then I left the middleware in place but reverted the NGINX configuration. It finally worked. I don't know why.

Now connecting to the back-office would fail with upstream sent too big header while reading response header from upstream errors being logged. That one was easier, it's an FAQ and applying the fix to NGINX configuration fixed it all.

At that point we have: a functional back-office, and broken sites due to...

Data Types

A range of data types are gone or have changed. And of course my custom data types are CompletelyBroken™ which is not a surprise, since the back-office UI has been entirely rebuilt.

First, native data types. Basically, go into the Data Types back-office section, and re-assign those that have issues to the proper property type. Rather simple. Weird enough, a content list datatype is throwing in the back-office, because of its orderBy value. Something a migration did not catch? Manually re-saving the datatype fixes it.

And then, I actually use two custom data types:

ZpqrtBnk.ImageFocus is an image focus data type which is an alternative to crops. It allows the user to define a rectangle that represents the "zone of interest" of an image. That zone is defined on the media itself. Next, whenever we need to render the media, we can automatically figure out the best crop based upon this zone.
ZpqrtBnk.Markdown is a custom Markdown data type that uses the back-office widget pretty much unchanged, but implements some rendering helpers for links or images.

As far as Markdown is concerned, I was using a property editor in order to support additional custom syntax. Turns out a property editor is not needed anymore, a plain IMarkdownToHtmlConverter implementation is all that is needed. So, the property editor is gone, and it is way nicer this way.

On the other hand the image focus editor needs to be completely rebuilt.

My First Property Editor

There is some nice documentation about property editors in v17, so let us follow it.

mkdir PropertyEditors
cd PropertyEditors
npm create vite@latest ZpqrtBnk.ImageFocus
# with Lit
# with TypeScript
# without Vite RollDown (but I was not proposed it)
cd ZpqrtBnk.ImageFocus
npm i && npm install -D @umbraco-cms/backoffice@17.4.0
rm -rf public/* src/*

Then,

Update vite.config.ts
Create src/zpqrtbnk-imgfocus.element.ts
Create public/umbraco-package.json

Is all it takes. OK, it takes a bit of time to figure out how to put everything together but hey, this is my very first time with the new UI. The end result is quite polished. As in, it makes way more sense than the convoluted Angular version.

In the end,

npm run build

Drops files in my site's App_Plugins and we are done. As in, it just works. I have to say the experience is quite pleasant.

Models

We are not entirely done with backend work. A few more things have changed, including the CLR type of objects returned by various data types. So, most of our models are broken.

The new MediaPicker3 for instance does not return a plain IPublishedContent, but a MediaWithCrops. I do not care about crops. And I had a media converter ensuring that the property value type would be reported as Image in case the picker can only pick one single image. So... that converter needs a bit of update to report the proper type, and to unwrap MediaWithCrops to Image wherever appropriate.

And then, with the various changes applied to property types, I though I would rebuild my models. Turns out they were built using the Our.ModelsBuilder edition of the Models Builder, not the built-in one, because I am using some extra features.

Well, a few more hours were spent bringing Our.ModelsBuilder to 2026 standards. It still is a huge mess, but at least it is working again. I have pushed the changes to the repository. I do not believe anyone uses it anymore, but hey. It has advanced features that Core does not provide.

Wrapping Up

At this point, I have a running back-office, clean data types, everything is nice, time to test the front-end.

And... it works.

What else can I say? Total time spent is probably 1 to 2 days of work. I like it way better than rebuilding everything, I really like that it this used to be a v4 site :) It is funny to see how many things have not changed much over the past 4-5 years, in terms of low-level concepts. On the other hand the experience is getting way more polished and user-friendly. And I love the new back-office.

The new Markdown editor does not seem fully stable, but probably it will get better with 18.

Good work, team!

Reverse Engineering with Claude - Masquerade

sgay@pilotine.com — Sun, 12 Jul 2026 19:00:00 Z

As much as I can enjoy playing games, to me it cannot compare to the pleasure of tearing them apart and figuring out how they all work. Which is just another kind of game, I guess. However, reverse-engineering has this issue that it is horribly time-consuming. When I release xrick, a Rick Dangerous remake, about 25 years ago, people were quick to ask for Rick Dangerous II. But I simply do not have the time it takes to reverse games while having a full-time job and a family.

Masquerade

On my list of games I have always wanted to reverse-engineer is Masquerade. An Apple II game by the late Dale Johnson, published in 1983 by Phoenix Software, with graphics by Rick Incrocci. It likely is one of the most difficult adventure games written for the Apple II.

This is mainly due to the fact that the game can only be won by using items in the one correct sequence, yet these items can be used in multiple ways, and using an item in the incorrect way will open up new locations, without the player being able to realise they have entered a dead-end. It also can require double actions (where the player has to perform the same action twice to fully solve a puzzle), which only compounds its difficulty.

The pitch is:

It turned out to be the toughest case of your detective career. Clues have led to nothing but dead ends. Nobody is talking. Mean-while, the crime boss you are after is still operating from somewhere. You're about to throw in the towel. But wait! Something breaks. You trail a stooge of the crime organization to a cheap, seedy hotel, hoping to pump some answers out of him. You break into the hotel room and with the butt end of your trusty .44 magnum, you knock him cold. This could be the lead you've waited for. Maybe, just maybe, if you could find some clues...

For more infos, feel free to head to this serie of articles that go over the origins and history of Masquerade, along with a walkthrough of the game. Or go play the JavaScript version here.

Reverse Engineering with Claude

Enters Claude. AI is supposed to be magic and can it help with reverse-engineering?

If I do not have the time, could I rely on Claude to do the work for me? Of course it would not be as entertaining, but I thought it would also be a good learning experience. And so... the rest of this post will be all about how I reversed Masquerade using Claude.

The Landscape

The things you need in order to reverse a game are, ideally,

An emulator for the platform - we are going to use the Bobbin emulator. It is not the best nor most known Apple 2 emulator, but it runs in text mode, and is very simple.
A disassembler - we are going to use Ghidra, the free and open-source disassembler originally from the NSA.

And then, since we want Claude to do the work for us,

A way for Claude to control the emulator - we are going to use the Bobbin MCP server. It runs on top of a forked Bobbin version which implements features in order to connect with the MCP server.
A way for Claude to control the disassembler - we are going to use the Ghidra MCP server.

Masquerade requires that you boot on "disk 1" and then at some point swap to "disk 2". Ejecting and inserting disks is not supported by the Bobbin MCP server yet: it was an easy job for Claude to patch the MCP and implemented disk swapping support.

Somehow I wanted to run it all on Windows, but Bobbin does not compile on Windows natively. You are supposed to cross-compile it from Linux via MINGW, and that scared me. So I asked Claude to figure things out and build on Windows. I am rather unhappy with the result: it works, it is super messy. Soon as I have some time I will revert to the original Bobbin source code and cross-compile it.

All in all, I will probably push a PR for the Bobbin MCP and Bobbin itself.

Let's Get Started

Once the environment is in place, you want to produce a dump of the emulator's memory, once the game is running. This works mostly because these old games were all loaded at once in memory and would not access the disk. Otherwise... things would be much harder.

So: boot Bobbin, run the game, and when the prompt shows, dump the entire Apple 2 64K memory. The game probably only uses a small portion of this memory, as it also contains the stack, the ROM and system code, the display memory... but hey, 64K is not that much, right?

Then: run Ghidra and load the binary as 6502 assembly code. Verify that the MCP is running and that Claude can use it.

And we are ready. Tell Claude that Ghidra is running and contains a memory dump of an Apple 2 game and please make sense of it. Tell Claude we want to build a knowledge base about the game, so its findings should be written down and organised.

I am immediately impressed by the result. Claude finds the RESET vector, the game's entry point, and the game's data structures and functions. It identifies entities (such as objects or characters), locations, and game mechanics and movement rules. In minutes, it is doing the archeological reverse engineering work that would take days, weeks or months by hand.

It is good to monitor it, though, as at some point it may go slightly sideways. For instance, when Ghidra stopped responding for a while, it decided it needed to build its own disassembler tool in Python or maybe Rust for performance reasons. About time to hit ESC and tell it that "you should use Ghidra exclusively, do NOT build your own disassembler tool, if Ghidra stops responding let me know and abort".

So at this point your role is baby-sitting Claude and stopping it anytime it goes off-track or starts making up things, but other than that it just works.

Porting to JavaScript

And then I made the mistake. It felt we knew enough of the game to roughly understand it, I got impatient, and I asked Claude to write a JavaScript port. Which it did pretty quickly. Alas... although it looked OK on the surface, it was full of tiny bugs and mistakes. Some movements were wrong, some entities were missing, etc.

Like, you move to the room that is supposed to contain the OLD BOOK, and there is no book there. So you ask Claude to fix it, and it explains that actually the entity table is not complete, some bits are missing, it requires some work... and now it is fixed.

Only it is not, or something else is broken. In fact, wherever the knowledge base appeared incomplete, Claude just made things up along the way.

And it is all my fault. I secretely hoped that wherever the knowledge base would appear incomplete, Claude would flag it and somehow complete it. Instead, Claude produced the most probable output based upon context. Claude has no notion of context reliability, context is just context.

Harness All The Things

"Harness" is the trendy word of the week in AI. "Harness" is the ability to use AI to assess the quality of AI-generated output. So... tell Claude that thanks to the Bobbin MCP, it has access to:

The actual, original, game running on a true Apple 2
The JavaScript version of the game running in a browser
A disassembler that contains and can disassemble the game's machine code

And what would it propose in order to make sure that the port is correct? Claude seemed super excited by that prospect, and proposed a detailed plan to compare the two executions, calling Bobbin "The Oracle" and JavaScript "The Candidate" (yea...) and using a generated set of test cases to compare their outputs. It would then compare the assembly code with the JavaScript code to identify discrepancies, and propose a corrective plan.

Sounds good?

To make it short... after burning tokens like crazy for a few days, making iterative updates and plenty of very convincing steps, we had fixed some bugs, introduced new bugs, and still the JavaScript port was broken.

Out of despair I asked Claude to assess its chances of converging to something that would be correct after a finite amount of time. To which Claude candidly replied that achieving correctness that way was probably impossible, and that it could continue drafting ever more complex strategies, but probably would just make things worse.

In a moment of honesty (and self-awareness) it even discoursed on the fact that, having no concept of anything, it had no concept of what "correct" meant, and that it was just trying to produce a port from a knowledge base that was not comprehensive enough.

Reboot

So... a second attempt was started. First, remove everything related to the first JavaScript port. In fact, instruct Claude to redact the knowledge base and remove every notion of "a port".

Then, ask Claude to assess the knowledge base and determine if it is comprehensive enough. Ask Claude to find out any function in Ghidra that would not be covered by the knowledge base. To verify every knowledge base assertion against Ghidra. To determine whether the knowledge was sufficient to perform a mechanical, line-by-line implementation in any other language.

Immediately Claude identifies gaps, performs more analysis, and confirms that now the knowledge base is complete enough. Ask again, though, and Claude finds more gaps. Essentially, I had to repeat the process over and over again until the gaps were meaningless and the changes to the knowledge base anecdoctical. Despite all my attemps, I could not convince Claude to "not trust your judgement and repeat until all gaps are really resolved".

After a number of iterations, though, we decided that we knew enough to move on. The port to JavaScript was then fast, cheap, straightforward and correct. I have been playing the walkthrough, plus some variations of it, and it works perfectly.

The result is online here. Let us see if you can solve it without cheating nor using a walkthrough. FWIW I have also pushed here on GitHub the entire workspace: disk images, memory dumps, Claude knowledge base, etc.

Lessons Learned

Claude can definitely help with reverse engineering. As in, saving weeks of work.

Wishful thinking is the cardinal sin of AI. Claude only produces the statistically most probable output considering context - it has no concepts of anything including context quality and completeness. If you are not fully confident that the context is complete, do not expect Claude to sort of make sense of it for you. You are the brain, the one that makes sense.

Harnesses are a horribly expensive and yet non-deterministic way of fixing this. Claude does not learn from the harness experience, it just repeats itself again and again hoping that at some point things will be good enough.

Claude does not understand doubts, regrets nor caution. As soon as a path becomes plausible enough, it becomes some sort of magnet that drags everything - and even an obvious mountain of inconsistencies is not enough for Claude to decide that maybe it took the wrong direction. Where human beings would start doubting, and maybe backtrack, Claude will get deeper and deeper into nonsense. It is critical to not let it move too fast, but monitor its activities and abort whenever necessary.

Human beings are able to take one direction while entertaining another one in some corner of our brain and, confronted to difficulties, start comparing the two. We are driven by intentions, purpose, as well as a notion of time (e.g. impatience). We understand. Claude on the other hand has knowledge, a lot of knowledge, and the ability to produce expected output very fast. As long as there is a reasonable probability of determining what is expected.

Give Claude context, and ask Claude tasks that only match the level of maturity of the context. Claude should progress quickly, without entering side quests. Anytime Claude starts to broaden its "thinking", abort it. Ask what should be done so it does not have to go sideways. Be a control freak.

Claude is a marvelous tool. Yet it is the tool. And the human is the craftsman.

Careful with that Struct

sgay@pilotine.com — Sat, 10 Jan 2026 16:00:00 Z

Method Chaining is a general pattern where an object class implements methods that alter the state of the object, and return the current instance, thus allowing code such as:

var c = new C();
c.ChangeThis(123).ChangeThat(456);

For instance, this very minimal C# example:

class C
{
  private string? _s;
  
  public C Change(string s)
  {
    _s = s;
    return this;
  }

  public override string ToString() => _s;
}

Could be used with the following results:

var c = new C();
c.Change("a");
Console.WriteLine(c); // writes 'a'
c.Change("b").Change("c");
Console.WriteLine(c); // writes 'c'

Now let's say we want to be clever and for some reason we decide to implement the pattern on a mutable struct:

struct C
{
  private string? _s;
  
  public C Change(string s)
  {
    _s = s;
    return this;
  }

  public override string ToString() => _s;
}

Can you predict the output of this code?

var c = new C();
c.Change("a");
Console.WriteLine(c); // writes 'a'
c.Change("b").Change("c");
Console.WriteLine(c); // writes ??

Turns out, but the second write will be 'b' not 'c'. How come?

It goes like this. We know that struct are passed around by value. More precisely, they are copied around when passed or returned to functions. Except of course for their own functions, which act on the struct itself. So when the Change method is invoked directly on the c variable, it operates on the actual structure owned by the c variable, and thus mutate it. This is why the first line writes 'a'.

However, the Change method also returns a C instance. And we just reminded ourselves that struct instances are copied around, so Change returns a copy of the structure owned by the c variable. So after the c.Change("b") call, both the structure in the c variable, and its copy, have a 'b' value.

But the chained method then operates on the copy! The copy is modified, and the result is ignored. The original structure owned by the c variable is not modified a second time. The second line writes 'b'.

Of course, if we do not ignore the returned value, things work as "expected":

c = c.Change("b").Change("c");
Console.WriteLine(c); // writes 'c'

So what is the conclusion here? Of course, it could be "do not mutate structs", which certainly is a valid general principle, but maybe a bit radical. On the other hand, it seems fairly reasonable to recommend against chaining methods for mutable structs.

Tales of FPGA - Road to SDRAM - E04

sgay@pilotine.com — Sun, 05 May 2024 20:00:00 Z

This post is the fourth one of a serie:

Episode 1 presents what FPGA are and how to control them
Episode 2 highlights the importance of time in FPGAs
Episode 3 presents the different types of RAM

The ultimate goal of this serie of posts is to provide a simple working example of a design that can reliably access the SDRAM chip on a Digilent Arty S7 FPGA development board.

And now, the time has come to actually try to implement access to that SDRAM chip. Of course there is the easy way: Xilinx provides an IP, the MIG (Memory Interface Generator), that just does it. OK, its documentation is about 600 pages so maybe "just" here is a gross simplification, but nevertheless.

It essentially generates a module that, to keep things simple, expose an address bus, a data bus, and a few control lines. On the diagram below, the block to the left is you, the user. The block on the right is the SDRAM chip. The block in the middle is magic.

By carefully following the rules, I managed to produce a complete design that can write-then-read-back data to/from the SDRAM, and blink a LED if everything is OK. Done.

However, (a) that IP is very generic and therefore has latencies introduced here and there. In other words, it is not giving you access to the SDRAM at the full speed it could support. And of course, (b) it is not fun.

Which takes us to the alternative: read the DDR3 protocol specifications, and implement them. Sorry to disapoint, but I am not going to enter into the details of DDR3 here. It is quite hairy and well documented. Google is your friend.

Let us just say that the protocol is mostly serial, so serialization and de-serialization of the data bus is involved. Reading one address implies sending a stream of commands to select the correct bank and row, then receiving the value.

It took me quite some time (and more), but I managed to implement a complete memory controller that Vivado would happily build and simulate. As in: we can observe the lines going to the (simulated) SDRAM chip change according to the specs, the chip behave just as it should, data goes in and out.

In the simulator.

#Fail

Once I tried to synthetize and implement the design on silicon, things turned pretty ugly. Vivado complained about timing issues. Lots of timing issues. As in, thousands of them. There was not a single part of the design that did not make it cringe.

Of course, sending the design to the actual physical board plainly failed to work and, as we have explained before, there is little we can observe. No debugger, nothing. Only this: it works on paper, it works in the simulator, it fails in Real Life.

Bummer. My idea was to get it to work, and sort of brag about how, yes, I have been able to make it work. Unfortunately (and that explains the delay between this article and the previous one) I must face reality: I failed.

Of course I wondered how Xilinx thought we were supposed to access the SDRAM chip.

The Black Box from Hell

So I started to break that black box open, in order to learn what magic tricks allowed it to work. And here is what I learned: SDRAM clocks are fast, as in, above 600MHz. And at that kind of speed, everything matters. If you have an 8-bit bus to the SDRAM chip, the actual placement of the logic controlling each bit on the FPGA chip makes a difference. Even the length of the path between the FPGA chip and the SDRAM chip matters. Oh, even the temperature of the SDRAM chip has an impact, and you are supposed to monitor it and re-calibrate everything when it changes.

And Xilinx's IP is a powerfull wizard indeed, which not only generates Verilog code, but also additional files that position each specific gate and component at a precise place on the die, and constantly monitors the temperatures, the delays, etc. and adjust for them.

There is no way I want to understand, nor replicate, all this stuff. I don't really want to deal with the physical world—I am happy with the logical one. Plus, it is kind of a moot exercise that Xilinx engineers have already solved.

And yet, it is frustrating.

Enters the PHY

I wanted to find some sort of in-between solution, which would give me control over the DDR3 protocol, yet deal with all the physical layer for me. And it turned out that Xilinx design sort of provides this. Internally, the black box is a pipeline of smaller black boxes:

And it turns out that the box named "PHY Interface" on this diagram implements precisely this: the complete control of the nitty-gritty of the physical layer, plenty of components such as "phasers" which are used to keep multiple signals in sync when for instance temperature changes would cause them to drift apart.

Interesting for sure, but way too close to the physical world for my liking.

Extracting the PHY layer from the global MIG IP is not an easy task, as it seems it was never meant (by Xilinx engineers) to be extracted for real. Oh, and the code is not exactly as clean as the diagram presents it, and even figuring out what is or is not in the PHY is not obvious.

Nevertheless, this has allowed me to produce a module that can reliably read and write commands and data to the SDRAM chip, as fast as the DDR3 protocol allows, and nothing more. A bit more work let me re-wire my original memory controller on top of this module, and voila, it all worked.

TADA!

And no, I will not describe it here. It would be pointlessly complex, and probably of no interest if you do not plan to use it yourself. That being said, the entire code is available on my GitHub.

Now what?

The reason for all this exercise is that I have implemented, on the FPGA, a SOC (system-on-chip) composed of a custom 8-bit CPU loosely extrapolated from the 6502/6809 family of chips, along with 64KB of RAM, VGA, and PS/2 keyboard.

It works quite well but currently only runs within its 64KB of RAM, which may not be enough if I want to, say, implement a TCP network stack and a small HTTP server. Having access to the full 256MB of the SDRAM chip would certainly help.

Hence our next challenge: how does an 8-bit CPU with a 16-bit address bus (i.e. a 64KB address space) handle a 256MB memory space in a nice and efficient way? Want to read about MMUs (memory management units), memory paging and banking, segments? Stay tuned!

TaskCompletionSource Pitfalls

sgay@pilotine.com — Sun, 14 May 2023 16:00:00 Z

Imagine you are implementing a client for a server that performs an operation on some data, and that operation is totally asynchronous, and the server has only one connection to it.

Contrary to an HTTP server, where a new connection is opened for each request (or, where requests are queued on one connection), requests must be pushed to the server with some sort of unique identifier, and the server will push responses back in whatever order it produces them.

Let us try to implement the client API:

~csharp
public async Task<Response> SubmitRequestAsync(Request request)
{
    await server.SendRequestAsync(request);

    // now what?
}

Here, we have to return a Task<Response> that represents the client waiting for the response... but what shall we be waiting on? Due to the full asynchronous nature of the server, we probably want to store the request in some sort of lookup table, and then wait for the corresponding response:

~csharp
public async Task<Response> SubmitRequestAsync(Request request)
{
    await server.SendRequestAsync(request);

    _requests[request.UniqueID] = request;

    // now what?
}

We need a background task that listens on the connection and receive responses:

~csharp
public async Task HandleResponses()
{
    while (true)
    {
        var response = await server.ReceiveResponseAsync();

        // now what?
    }
}

Still, what should the SubmitRequestAsync return, that we could await? And how should the HandleResponse method complete the API call?

TaskCompletionSource

The TaskCompletionSource is a nice feature of .NET that allows a developer to create "something that creates a Task" and then explicitely decide when to complete, cancel or fail that Task. Using a completion source, we can finalize our API:

~csharp
public async Task<Response> SubmitRequestAsync(Request request)
{
    await server.SendRequestAsync(request);

    var completion = new TaskCompletionSource<Response>();

    _requests[request.UniqueID] = request;
    _completions[request.UniqueID] = completion;

    return completion.Task;
}

Here, we create a completion source, and return its Task. This is a "logical" task: there is no executing code corresponding to it. It just represent "the execution of something". And that execution would be completed by the background task:

~csharp
public async Task HandleResponses()
{
    while (true)
    {
        var response = await server.ReceiveResponseAsync();
        var completion = _completions[response.UniqueID];
        completion.TrySetResult(response);        
    }
}

The task retrieves the completion source corresponding to the unique request identifier, and completes it by assigning it a result. In a more elaborate scenario, it could also fail it by assigning it an exception, or even cancel it.

NOTE: this is a simplified version of the code. In real life, we would need to ensure thread safety, remove requests and completions from their lookup tables, etc.

Yes, but

We could end the article here, but... there's a but. What do you think happens when completion.TrySetResult(response) is invoked? Intuitively, we assume that:

TrySetResult returns from the call and the while loop repeats;
Whatever code was awaiting the completion's Task is unlocked and starts running.

In other words, invoking TrySetResults fork a new parallel code execution path that resumes whatever code was await-ing the completion's Task, while the main code execution path continues looping the while loop.

However—and here is the but—.NET tries to optimize asynchronous calls to avoid unnecessary and expensive management of tasks and threads. You have probably heard that when invoking the following method, the call to DoSomethingElse will run immediately and synchronously, and that the method will only return a Task when it encounters the first await statement:

~csharp
public async Task DoSomething()
{
    DoSomethingElse();
    await DoYetAnotherThing();
}

It turns out that the very same thing happens with TrySetResult. .NET will immediately run the code that is await-ing on the completion's Task, and the call to TrySetResult will only complete after either that code is done running, or an await statement is encountered.

And then it all fails

Now look at the following code:

~csharp
public async Task HandleResponses()
{
    while (true)
    {
        var response = await server.ReceiveResponseAsync();
        AquireSemaphore();
        var completion = _completions[response.UniqueID];
        completion.TrySetResult(response);        
        ReleaseSemaphore();
    }
}

public async Task UseTheAPI()
{
    var response = await SubmitRequestAsync(request);
    AquireSemaphore();
    // do something with the response
    ReleaseSemaphore();
}

What do you think will happen? Spoiler: it will deadlock. The call to TrySetResult will complete the SubmitRequestAsync call and flow and continue the UseTheAPI method. It will try to run AquireSemaphore in UseTheAPI before returning, and will fail to get the semaphore, because it has already been acquired. It will never return, and never release the semaphore, and everything hangs.

In other words: invoking TrySetResult is not a fire-and-forget thing. In most cases it will be OK, but in some situation it can lead to deadlocks and other oddities, where a lot happens between the moment TrySetResult is invoked and the moment it returns.

Uh, what shall we do?

In some situations, we really don't know what may be await-ing the completion's Task. What we want is a way to tell .NET: don't be clever. Submit whatever is await-ing to the thread pool and return immediately. Run it all on separate tasks. It may be a little more expensive, but at least invoking TrySetResult would become deterministic.

There is an option to do this, but it is not a TrySetResult option. Instead, it needs to be specified when creating the completion souce. The class constructor has an overload that supports a TaskCreationOptions that can be used to indicate how the tasks resulting from TrySetResult are supposed to run.

Especially, TaskCreationOptions.RunContinuationsAsynchronously specifies that "continuations added to the current task [are] to be executed asynchronously." We can create our continuation as such:

~csharp
var completion = new TaskCompletionSource<Response>(
    TaskCreationOptions.RunContinuationsAsynchronously
);

When TrySetResult is invoked, it submits all the continuations on the completion's Task (i.e. all code await-ing that task) on the thread pool for execution, instead of running them, and returns immediately.

Nice, why is this not the default?

Because in most cases, this is an overkill. Whenever TaskCompletionSource instances are used in simple and controlled environment, everything should be OK and it's better to let .NET optimize everything.

Nevertheless, it is good to be aware of this pitfall.

Faster GitHub PR check time with multi-level matrix strategy

sgay@pilotine.com — Mon, 26 Sep 2022 12:40:00 Z

The Hazelcast .NET¹ Client is provided as a library that is supported on .NET (Framework) version 4.6.2 to 4.8, .NET (Core) 3.1, and .NET (Just .NET) 5.0 and 6.0. For .NET Core and Just .NET, the library is supported both on Windows and on Linux. This means that we want to run our complete tests suite on both platforms, for each supported .NET version.

Originally, we defined a Build PR workflow that would trigger on each PR and build and run the tests for each .NET version supported by the platform, one after another. In order to test both platforms, we used an OS matrix strategy:

name: Build PR
on: pull_request

jobs:
  build-pr:
    name: Build PR (${{ matrix.os }})
    runs-on: ${{ matrix.os }}

    strategy:
      fail-fast: false
      matrix:
        os: [ ubuntu-latest, windows-latest ]

    steps:
    - name: Build and Test the PR
      (etc)

Thanks to this, on each PR, two jobs would run in parallel: one for Linux, and one for Windows. However, on each platform, the tests for each .NET version would run sequentially. And thus... if the complete tests suite takes about 20 minutes to run, the Windows job would take net462 + net48 + netcoreapp3.1 + net5.0 + net6.0 = 5 times 20 minutes, or 1h40. Which is quite a lot of time to validate a PR.

Entering the Second Dimension

We want to reduce that time, and the idea is to parallelize each .NET version, in addition to platforms. On each PR, we would fork one job for .NET 5.0 on Linux, one job for .NET 6.0 on Linux, one job for .NET 4.8 on Windows, etc. The total build time would be approximatively the build time of one version or, in our example above, 20 minutes instead of 1h40.

GitHub supports 2-dimensions matrixes. For instance:

    matrix:
      os: [ ubuntu-latest, windows-latest ]
      dotnet: [ net5.0, net6.0 ]

In our situation, however, the list of versions to put in the dotnet dimension if not fixed and actually depends on the OS. We would need to write something akin to the following code, where get_dotnet_version would be a function returning the .NET version corresponding to the OS:

    matrix:
      os: [ ubuntu-latest, windows-latest ]
      dotnet: get_dotnet_versions(matrix.os)

Alas, GitHub does not support that type of construct. The only thing it supports is referencing a variable, such as an input, in the matrix. So we would need to be able to produce a unique variable, and yet its value would depend on matrix.os... again, that type of construct is not supported. All in all, I could not find a way to get one matrix dimension to depend on the other, within one workflow.

Divide and Conquer

Now... what-if instead of trying to do everything in one workflow, we used two? Our first workflow looks like:

jobs:
  getversions:
    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        os: [ ubuntu-latest, windows-latest ]

    outputs:
      # beware! this cannot be dynamic = must match the OS matrix
      versions-ubuntu-latest: ${{ steps.getversions.outputs.versions-ubuntu-latest }}
      versions-windows-latest: ${{ steps.getversions.outputs.versions-windows-latest }}

    steps:
    - name: Determine DotNet Versions
      id: getversions
      shell: bash
      run: |
        VERSIONS=$(....)
        echo "::set-output name=versions-${{ matrix.os }}::$VERSIONS"

  buildtest:
    name: Build&Test ${{ matrix.os }}
    needs: getversions
    strategy:
      fail-fast: false
      matrix:
        os: [ ubuntu-latest, windows-latest ]
    uses: ./.github/workflows/build-pr-on.yml
    secrets: inherit
    with:
      os: ${{ matrix.os }}
      versions: ${{ needs.getversions.outputs[format('versions-{0}', matrix.os)] }}

Let's go through this workflow. It contains two jobs, getversions and buildtest.

The first job, getversions, runs a unique step that determines the versions based on the platform, and sets a job output variable accordingly. That variable contains a JSON list of versions, e.g. [ "net462", "net48" ]. Actually, it sets one job output per platform, and I could not find a way to avoid hard-coding the platform names.

The second job, buildtest, does not run any steps, but instead triggers another workflow, passing two input parameters: the platform, and the list of versions. And this is where we manage to specify versions that depend on the platform.

And then, the magic happens in that other workflow. First, in order to be "callable" with input parameters, it requires this on statement:

on: 
  workflow_call:
    inputs:
      os:
        required: true
        type: string
      versions:
        required: true
        type: string

And then its job is defined as:

jobs:
  buildtest:
    name: ${{ matrix.fwk }}
    runs-on: ${{ inputs.os }}
    strategy:
      fail-fast: false
      matrix:
        version: ${{ fromJson(inputs.versions) }}

And there we have it: a build and test job that runs on the specified platform, for each specified versions. The last piece of the puzzle consists in wrapping in all into one single conclusion point. This is done via an additional job in the first workflow:

report:
    name: Build&Test Result
    runs-on: ubuntu-latest
    if: always()
    needs: buildtest
    steps:
    - name: report
      shell: bash
      run: |
        if [ "${{ needs.buildtest.conclusion }}" == "success" ]; then
          echo "All Build&Test checks completed successfully."
        else
          echo "At least one Build&Test check has failed."
          echo "::error::At least one Build&Test check has failed."
        fi

This job "needs" the buildtest job, in other words it will only run once all our forked build & test jobs have completed. It always run, and succeeds or fails depending on the outputs of all the forked jobs. This means that this is what we see in GitHub actions:

The block to the left shows the two jobs that run, on per platform, and figure out the framework versions for each platform. The center block shows each combination of platform / version build - they all run in parallel. Finally, the block to the right shows the global status of the build.

That last "Build&Test Result" block can be used as a required check in our GitHub branch configuration, thus ensuring that all test combinations must be successful before any PR can be merged.

All in about 20 minutes, not 1h40!

or maybe it is the "Hazelcast dotnet Client" or "Hazelcast Dotnet Client", depending on the success of the #dropTheDot movement initiated by Khalid at a time the .NET Drama Advisory (or should it be the Dotnet Drama Advisory) was pretty low and he got bored.↩

Tales of FPGA - Road to SDRAM - E03

sgay@pilotine.com — Tue, 13 Sep 2022 12:00:00 Z

This post is the third one of a serie which starts with Episode 1, in which we have presented what FPGA are and how to control them, and continues with Episode 2, in which we have discovered the importance of time.

The ultimate goal of this serie of posts is to provide a simple working example of a design that can reliably access the SDRAM chip on a Digilent Arty S7 FPGA development board.

In order to understand why we want to access that chip, let us first review the different types of RAM that can exist in a computer.

SRAM

The first and most simple memory type is Static Random Access Memory (SRAM). It is an array of memory cells and exposes:

An address bus which selects the cell
A data bus which contains the value to write, or the value that was read
A RW signal which indicates whether to read or write
A clock signal

On each clock signal, depending on the RW signal, the cells specified by the address bus are updated with the value specified by the data bus, or the data bus is updated with the value contained by the specified cells.

Each cell (i.e. each bit) is implemented with about six transistors, and is stable, or static: it keeps its value around for as long as power is supplied. Circuitry is minimal, and it is fast, as in: it can typically keep up with the CPU speed. In other words, the CPU can request a value on a clock tick, and read that value on the next clock tick.

(S)DRAM

Unfortunately, due to their transistors count, SRAM cells require a lot (relatively) of silicon, which implies low density and high costs. For instance, a modern Intel Core i9 CPU carries only about 90KB of SRAM L1 cache per core.

In order to increase density and lower costs, cells have to be simplified down to the simplest cell, which is composed of only one transistor and one capacitor: this type of cell is at the core of most modern memory types.

Its drawback is that it is not stable: its capacitor charge leaks and the cell loses its value after a while. Additional circuitry is therefore required to refresh (i.e. access) it periodically. Hence the name: Dynamic Random Access Memory (DRAM).

Due to their need to be refreshed, but also their density, DRAM have a different and more complex interface. Cells are organized in banks and rows and columns, which must be selected before any read or write can take place. A read or a write now takes several clock ticks, and more control lines determine which operation to achieve.

Simple, original DRAM operated asynchronously with the CPU's clock. In order to increase efficiency and throughput, they evolved into Synchronized DRAM (SDRAM) where everything is timed by the CPU. This allows for more optimizations such as pipelining: for instance, selecting the rows and columns of the next read, while receiving data for the previous read.

DDR SDRAM

In order to further increase the memory bandwidth and reduce latency, the frequency of the data line would need to increase. However, a higher frequency means more energy consumption and heat—this is the issue faced by all CPUs today.

To mitigate these side effects, Double Data Rate (DDR) SDRAM were introduced: they keep the same frequency, but transfer data on each edge of the clock, not only on each clock cycle, thus doubling the bandwidth.

DDR was followed by DDR2, DDR3, etc. standards which add more "tricks" to the SDRAM interface, such as burst reads & writes, all in order to increase the speed of memories.

Nevertheless, and despite all optimizations, SDRAM simply cannot keep up with modern CPU speeds anymore. The CPU cannot expect to request a value, and get it on the next clock tick, as it did with SRAM when computers had only a few KB of RAM. Modern CPU have to rely on various levels of caches and all sorts of optimizations in order to remain busy while waiting for memory reads and writes.

FPGA RAM

Now that we have reviewed the different types of memories, let us consider what exists on our FPGA board:

The FPGA chip itself contains some SRAM blocks that can run as fast as the rest of the chip. We have however seen that SRAM is expensive: our FPGA chip carries only about 338KB of RAM.
A separate chip on the board (the same chip you would find in a PC) provides 256MB of DDR3 SDRAM.

Accessing the SRAM blocks is relatively easy. Once instantiated in a design, one "just" needs to drive the address and data busses correctly. And, it is fast. Alas, the total available capacity is quite small.

Which leads us to the SDRAM chip. However, accessing that chip is an entirely different story, and the DDR3 protocol is a complex beast to implement. That will be the topic of the next post.

Tales of FPGA - Road to SDRAM - E02

sgay@pilotine.com — Tue, 16 Aug 2022 19:00:00 Z

This post is the second one of a serie which starts with Episode 1, in which we have presented what FPGA are, how to control them, and implicitly discovered their major benefit: they make the physical world rational and clean.

Indeed, the physical world a.k.a. "reality" is notoriously messy, as anyone who has tried to implement some design with discrete electronic components knows.

For instance, should we decide that "zero" is +0V and "one" is +5V... there are chances that the transistor-based AND gate that we carefully assembled on our breadboard outputs +4.8V for "one" and not +5V because, imperfections. If we feed that signal into anoter gate, it will probably be identified as "one". But if we keep doing this, then at one point we will end up with a +2.6V signal and what is that supposed to mean exactly? "Zero", or "one"? Our design lacks additional circuitry to ensure that we maintain the correct signal levels everywhere, we feed enough current, etc.

Another example: these 30 cm of wire flying over our breadboard and carrying a signal at, say, 100MHz? It is an antenna in the FM radio frequencies. It is going to broadcast that signal, as well as be impacted by existing radio signals on that frequency. Our design may randomly fail and, if carefully examining signals with a scope, we would see all sorts of very weird distortions.

FPGA have none of this: they are clean and reproducible. We write text files, have them processed by a tool, and end up with a hardware-level design that just works. If we make a mistake, there is no need for rewiring things, going to the shop to buy that one component we are missing, etc. We do not have to worry about radio interferences, current leaks, etc.

With FPGA, the physical world becomes deterministic.

Meet the Enemy

And yet, the FPGA designer has one enemy, and this enemy is time.

It is convenient to think of a LUT2 as something that immediately updates its output according to its inputs. In reality, it is almost immediate. In the FPGA chip we are using (a Xilinx Spartan-7 family chip), the delay would be around .15ns or 150ps. A flip-flop has a delay of about .55ns or 550ps.

Sure, 150ps is 0.000 000 000 150s and this is very small. Yet, the period of a 4GHz signal—a value one can meet in modern CPUs—is 250ps: a very small value too, but one which is very comparable, in scale, to the above delay.

It is also convenient to think of connections betweens elements as pure electric wires, carrying signals at the speed of light. In reality, signals travels the FPGA die at a slower speed, because connections are not just true electric wires. And then even at the speed of light, electricity only travels about 30cm per ns, or 3mm in 10ps, and considering the size of a typical chip die, 3mm might be the distance separating two LUTs.

Let us see what this means with an example.

This circuit increments a two-bits signal on every clock tick. The new square boxes are flip-flops: they update their output (the Q port) to reflect the value of their input (the D port) on each raising edge of their clock (the C port). So count will go 00, 01, 10, 11, 00, 01, etc. each time the clock ticks.

More precisely, when the clock ticks,

Flip-flops update their output to match their input after about .55ns
Gates update their output to match their inputs after about .15ns

So, count_next[1] will reach its new value after .55 + .15 + .15 = .85ns. This is called the propagation delay. And still, we cannot tick the clock immediately, because the flip-flops demand that the input be stable for some amount of time before the clock ticks: this is call the setup time. It is about .05ns in our case. And thus, the clock can only ticks again after .9ns have elapsed.

We are ignoring the connection delays here. So, let's round it all to 1ns. This corresponds to a frequency of 1GHz. Not too bad, but this is a very simple circuit.

Very quickly, things get complex, and the maximum frequency can fall down to 100MHz or even 10MHz. If we do not respect that constraint, things become completely unpredictable. If we are only slightly too fast, we might not respect the setup time, thus creating a situation called metastability: the data coming out of flip-flops may be randomly wrong. And of course, if we are really too fast, everything becomes random.

Know Thy Enemy

Tools such as the Vivado IDE do not simply convert code into a network of LUTs, flip-flops, etc. They also decide which elements to use on the chip (which can contain a few thousands LUTs, for instance), trying to minimize the physical distance between elements. And then, they process the resulting network and calculate all the propagation times and finaly issue a timing report.

Take the LED blinker from the previous episode. We would tell Vivado that the clock signal comes from "outside" of the chip, actually an oscillator on the development board, which runs at 12MHz. Vivado would report that at 12MHz, everything is fine. There is another oscillator on the board, which runs at 100MHz, and that should be OK too.

But imagine we have a 1GHz clock on the board: Vivado would definitively build the design (which we can then push to the board) but it would also issue timing warnings, telling us that our design has little chance to work.

When that happens, for instance when we try to run our carefully crafted CPU at 10MHz and Vivado complains about timings, there are essentially two solutions:

Slow the clock. Not very satisfactory, but simple enough
Refactor the design, maybe doing less per clock cycle (see: pipelining)

Were we not supposed to talk about SDRAMs?

We were, but that little disgression about time will prove useful in the next episode, where we will present the different types of RAM and see how RAM is essentially dictating time constraints in a modern design.

To be continued!

Tales of FPGA - Road to SDRAM - E01

sgay@pilotine.com — Mon, 25 Jul 2022 19:00:00 Z

This post is the first one of a serie, which aims at providing a simple working example of a design that can reliably access the SDRAM chip on a Digilent Arty S7 FPGA development board. Indeed, although this board has been out for quite some time now, such a design seems practically impossible to find on the 'net, for reasons we will try to analyze.

I also mean this serie to be an introduction to FPGA for people who have little idea what they actually are nor how they work. So, even if you do not care about accessing SDRAM on that particular board, you may find it an interesting read. In fact, my interest in FPGA owes a lot to the fact that they help understand the inner working of a CPU, a RAM, and any modern computer.

Arty S7?

The Arty S7 is an FPGA development board based upon Xilinx' Spartan-7 series of FPGA chips. It is a cost-effective design packing an FPGA chip, DDR3L memory, buttons, leds, I/O and expansion ports... everything you need to experiment with an FPGA at a reasonable cost (around USD 100.00).

In a way, it is similar to an Arduino board, with the CPU replaced by the FPGA chip.

And what is an FPGA chip?

An FPGA is a Field Programmable Gate Array: a semiconductor device based around a matrix of configurable logic blocks, connected via programmable interconnects. The most basic logic block would be, for instance, an AND gate:

When any of the gate inputs change, the output is adjusted, after a short inevitable delay. This type of gate can be implemented with a few transistors, and along with the other OR, XOR... gates they are the basic elements of all silicon-based operations.

In reality, FPGA do not implement AND gates, and their most basic logic block would rather be a 2-bit look-up table, or LUT2. It also has two inputs and one output, and updates its output according to its inputs. But the value of the output is specified by a 2x2 logic table. This way, one single block can be configured to be an AND, OR, XOR... gate.

And then there are LUT4, LUT6... which follow the same principle only with more inputs. You would also find flip-flops which can latch a stable state on a clock signal, oscillators, some type of memories, etc. that you can all configure in the same way one configures the logic table of a LUT2.

All these blocks are layed out in precise positions on the die of the FPGA chip. And then, there is an interconnect layer which can be configured to wire (pratically) any block input or output with any other block input or output. So you could configure a LUT2 as an AND gate, and wire its output to the input of another LUT2 configured as an OR gate, etc.

The whole configuration is represented as a blob of binary data which needs to be fed to the FPGA before it can operates. Traditionally, some additional hardware on the development board handle this process and read this blob from Flash memory, or allow the developer to upload it via an USB link.

Taking Control

FPGA manufacturers provide tools and development environments that let users configure their chips. Xilinx, a major FPGA actor owned by AMD, even have several of them, the most popular (and having a free edition) being the Vivado IDE. These tools support various description languages such as VHDL or Verilog or its SystemVerilog evolution. These languages are used to specify the FPGA internal configuration, as a set of text files.

The major difference with traditional programming languages is that all these elements and signals and connections operate concurrently. An FPGA design is a massively parallel thing.

This post is certainly not a VHDL nor Verilog tutorial. Let us just say that it all begins with a module which has inputs and outputs (connected to the actual external pins of the FPGA), along with internal signals, and defines connections between these signals. The following module would for instance act as an AND gate:

module and_gate (
    input logic in_0,
    input logic in_1,
    output logic out
);

    LUT2 #(
        .INIT (4'b1000)    // define the logic table
    )
    LUT2_inst (
        .I0 (in_0),        // wire module input in_0 to LUT2 input I0
        .I1 (in_1),        // wire module input in_1 to LUT2 input I1
        .O (out)           // wire LUT2 output 0 to module output out
    );

endmodule

The LUT2 logic table is documented as being a 4-bit value with the higher-rank bit (left-most) representing the output value when both inputs are 1, and thus, our LUT2 will act as an AND gate.

Vivado can then "compile" this design, provided that you also tell it how to wire the inputs and outputs of the module. For instance, inputs could be wired to buttons, and outputs to LEDs. The compiler will determine which LUT2 to use on the board, and produce the FPGA configuration binary blob, that Vivado can feed to the board via USB. There, done, our first design!

However, Verilog (the language) is way more clever than that. It does not merely "compile" the design, but synthesize it. It can infer which blocks to use, depending on logical syntax. Noone would ever write a module such as the one above. Instead, one would simply write the following code:

module and_gate (
    input logic in_0,
    input logic in_1,
    output logic out
);

    assign out = in_0 & in_1;

endmodule

The tools would determine that you are assigning out to be the logical AND between in_0 and in_1, and that the most convenient block to achieve this is a LUT2. It could as well understand that you want to add two 8-bit numbers, and select and wire together the relevant blocks: a large combination of LUTs maybe, unless the FPGA provides some built-in adder blocks.

In fact, most designs only explicitly instantiate complex blocks (clocks, memories...) but usually let the language deal with the rest (LUTs, flip-flops...).

The Obligatory LED Blinker

The following module accepts a clock logic signal as an input, produces a LED logic signal as an output, and would toggle that LED signal periodically, thus blinking the LED.

module testbench (
    input  logic clk,   // the logical input clock signal
    output logic led    // the logical output signal controlling the LED
);
    localparam COUNT_WIDTH = 8;

    // count and next_count are a multiple-bits signals of width COUNT_WIDTH
    var logic [COUNT_WIDTH-1:0] count, next_count;

    initial count = 0;

    // the next_count signal continuously updates to be count + 1
    // it's only bits: when count reaches its max value, it wraps to zero
    assign next_count = count + 1;

    // the led signal continuously reflects the highest bit of the count signal
    assign led = count[COUNT_WIDTH-1];

    // on each raising edge of the clk signal,
    // update the count signal with its next value
    always @ (posedge clk) count <= next_count;

endmodule

Note:

Things defined as var are internal signals, similar to a wire connecting blocks.
The assign statement means: the signal on the left-hand side of the = sign should constantly reflect the result of the expression on the right-hand site. They would probably be implemented with LUTs.
The always @ (posedge clk) means: the signals on the left-hand side of the <= signs should be updated to reflect the result of the expressions on the right-hand sign, on each raising edge of the clk signal. They would probably be implemented with a combination of LUTs and flip-flops.
count is an array of bits, containing COUNT_WIDTH bits. It is constantly incremented. If COUNT_WITH is 2, then count would be 00, 01, 10, 11, 00, 01, etc. and its highest bit would be 0 half of the time, and 1 the other half.

Assuming you tell Vivado to wire the clk input to the on-board physical clock, and the led output to a LED, and if you configure COUNT_WIDTH correctly as per the clk signal frequency... this should blink the LED on the board.

Or Maybe Not

And then what? There is no way you can plug a debugger into the FPGA. Remember, there is no "code" executing: everything is happening at hardware, electrical level, and you cannot inspect what happens at silicon level. For very large designs, Xilinx does provide some methods to add analysis features to your design and actually extract the value of some signals, but they are rather cumbersome and intrusive.

It is all a black box.

All you can do is go back to your design, and think.

On the other hand, FPGA tools such as the Vivado IDE can simulate a design, i.e. emulate the complete behavior of the elements, all within the PC memory. Vivado comes with a virtual logic analyzer, which shows the signals in details. Here is an example of waveforms it can produce.

Such an analysis will help you figure out your logical errors, to the point that the simulation is correct. And then... If the code does not have syntax errors, and the design simulates correctly, everything should run successfully on hardware too.

Let us stop on that (naïvely?) positive note here.

To be continued!

IAsyncDisposable Pitfalls

sgay@pilotine.com — Tue, 19 Jul 2022 13:00:00 Z

The .NET ecosystem comes with more and more sophisticated Roslyn Analyzers which may seem annoying but actually are quite useful at improving our code and detecting hidden and tricky issues.

Say we have a Method method that uses a thing object, which implements IAsyncDisposable and is produced by an async GetAsyncDisposableAsync method. We know about the await using pattern, which guarantees that the object will be async-disposed when the method exits. We have learned that we need to use ConfigureAwait on awaited tasks (else, we get the CA2007: Do not directly await a Task warning). And so, we write the following code:

public async Task Method()
{
    await using var thing = await GetAsyncDisposableAsync().ConfigureAwait(false);

    // use the thing
}

It is a bit convoluted, but does what we want.

Or, does it?

Recently, This code started to produce the CA2007: Do not directly await a Task warning) again. Despite the fact that we are, well, obviously not directly awaiting the task.

Or... which task? It turns out that there are two tasks at stake here:

When we obtain the thing object, we run the async GetAsyncDisposable method, which returns a Task<IAsyncDisposable>, which we await immediately
When the await using pattern implicitly async-disposes the object at the end of the method, it runs the async thing.DisposeAsync method, which returns a ValueTask, which is awaited

When we write the following code, where GetAsyncDisposable is synchronous, the compiler will reuse the ConfigureAwait statement when awaiting the DisposeAsync task.

await using var y = GetAsyncDisposable().ConfigureAwait(false);

However, when we write the following code, where GetAsyncDisposable is asynchronous, the compiler has to use the ConfigureAwait statement immediately and is left with no hint about how to await the DisposeAsync task.

await using var y = await GetAsyncDisposableAsync().ConfigureAwait(false);

And, don't think about putting two ConfigureAwait statements there, it does not work. There is a lengthy discussion about this situation in the C# lang repository, which essentially concludes that there is no pretty way to handle the situation. It's one area where the C# design fails.

Solution (sort-of)

The solution idea is to separate the await using statement from the retrieval of the IAsyncDisposable object. In other words: don't await using something that is obtained asynchronously. Our code can become:

public async Task Method()
{
    var thing = await GetAsyncDisposableAsync().ConfigureAwait(false);
    await using (thing.ConfigureAwait(false))
    {
        // use the thing
    }
}

And now we do have our two ConfigureAwait calls, and C# will use the one in the await using block when awaiting the DisposeAsync ValueTask. Note however that we lose the convenient one-line await using syntax. We can get it back with this other version:

public async Task Method()
{
    var thing = await GetAsyncDisposableAsync().ConfigureAwait(false);
    await using var thingd = thing.ConfigureAwait(false);

    // use the thing
}

The discussion on the C# repository proposes even more esoteric solutions and some weird-looking extension methods that, in my mind, render things even more confusing. It is an interesting read nevertheless :)

The Curse of NULL

sgay@pilotine.com — Fri, 10 Jun 2022 19:35:00 Z

C# has two main categories of types: value types and reference types. A variable of a value type contains an instance of the type, while a variable of a reference type contains a reference to an instance of the type. In a very non-technical way, one could say that a value type variable is the "thing" itself, while a reference type variable points to the "thing".

An integer, for instance, is a value type. An integer variable contains the value itself. It has to be a valid integer value (in the int.MinValue to int.MaxValue range), and is zero by default. And technically, anything that can fit in a value type (ignoring struct here) is valid: if an int is composed of four bytes i.e. 32 bits, any combination of these 32 bits is going to produce a valid int.

An object can be a reference type, when it is defined as a class. A class object variable contains a reference to the object, not the object itself. More precisely, it contains a number (32 bits on 32 bit OS, 64 bits on 64 bits OS) which is the address of the object in memory.

A reference type variable has to point to a valid object of the correct type, and of course not every number point to such an object: some numbers would be invalid. Luckily C# makes sure that, by default, all reference variables are valid.

Except for one situation.

Enters NULL

C# allows reference type variables to use the underlying value zero a.k.a. null, which is not a valid memory address, to indicate that they actually do not point to an object. It can be convenient, when you think of it, and the concept is widely used in databases: if the Name column contains null, we don't know the name of the person.

At C# code level however, null is sort of cursed. And why so? Because... if the variable thing is of type Thing which is defined as a class, and the value of the variable is null, what is the value of thing.Value? It cannot be determined, and trying to access it provokes a NullReferenceException at runtime. Once null is authorized, programmers have to take great care everywhere to handle, and guard against, null.

Oh and, the default value of a reference type variable is null.

Nullable Value Type

Now imagine that one wants a variable that indicates whether a user is OK with receiving spam, and aso imagine that this variable is meaningless as long as the user has not explicitly indicated whether they are OK with spam or not. Unfortunately, a bool variable is true or false and nothing else. Of course the proper way do handle this would be via two separate variables:

~csharp
bool isOkWithSpam;
bool hasIndicatedSpamPreference;

But, inspired by the null usage for references, C# introduced the Nullable<T> structure which can at the same time carry a value, and indicate whether it has a value or not. And, to make it even friendlier, it introduced syntactic sugar that would allow one to pretend that the variable could be null:

~csharp
bool? isOkWithSpam;    // compiles as: Nullable<bool> isOkWithSpam;
isOkWithSpam = null;   // compiles as: isOkWithSpam.HasValue = false;

Note that a Nullable<T> has "interesting" properties. You probably know already that the C# language can "box" an integer value type into an object. In the code below, the o variable is of type object and contains an actual System.Int32 value, obtained at the time of boxing (don't confuse it with a reference to i— such a reference does not exist and changing i does not change o):

~csharp
var i = 33;
var o = (object) i;
Console.WriteLine(o.GetType()); // "System.Int32"

Now what happens when you box a Nullable<T>? You may think that you would get a variable of type object containing an actual Nullable<T> value. But actually... boxing unwraps the Nullable<T> structure, and what you finally get depends on whether there was a value or not:

~csharp
var i = (int?) 33;
var o = (object) i; // o is of type System.Int32
var ni = (int?) null;
var no = (object) ni; // o is null

All in all, the C# language support for nullable values is pretty nice, you can even sum several int? value and get an actual result if no value is null, or null if one value is null... The language designers looked at nullable value type variables, and thought it was a very good thing.

Nullable Reference Type

Others found that the whole concept of a variable being null was very wrong and dangerous. They thought that a string variable should always contain an actual string, no matter what, maybe the empty string by default, but not never ever nothing.

However, imposing such a change on the CLR would be a massive breaking change. Actually, an impossible one. So they had this idea: technically, the CLR would still support null references, but the compiler would try its best to detect and prevent them.

When the nullable feature of the compiler is enabled, a string variable is assumed to be non-null. The following code would raise a warning (note: not an error).

~csharp
string s;
s = null; // warning!

And, for consistency purposes, the value type nullable notation has been reused to indicate a reference variable that is authorized to be null:

~csharp
string? s;
s = null; // no warning

Though initially annoying, this can quickly point to errors in code and is in fact quite nice.

Some caveats: if you write a library that expose a method such as:

~csharp
public void WriteLength(string s)
{
    Console.WriteLine(s.Length);
}

The compiler will assume that this is safe, since the variable is of type string, which indicates it cannot be null. However, remember that this is a compiler-level check. Nothing prevents a user of your library to disable the nullable checks, and pass null to your method. Therefore, it is still a good practice to check parameters for null values in publicly-exposed methods:

~csharp
public void WriteLength(string s)
{
    if (s == null) throw new ArgumentNullException(nameof(s));
    Console.WriteLine(s.Length);
}

But for everything internal, it should be safe to trust the compiler.

And then it becomes complicated

Now imagine a function that may return a value, or may want to indicate that it has no value to return. This is a typical use case for nullable.

~csharp
public T? GetValue<T>() { ... }

Alas, with C# 8, that would not compile. The problem here is that T? can mean two very different things:

If T is a value type, T? is syntactic sugar for Nullable<T>.
If T is a reference type, T? is actually T but with a hint for the compiler to assume that the value can be null.

We end up with a function that can return Nullable<T> or T, which is an impossible situation. One has to constrain T for the code to compile:

~csharp
public T? GetValValue<T>() where T : struct { ... }
public T? GetRefValue<T>() where T : class { ... }

C# 9 has a better support for nullable, and does compile the following function:

~csharp
public T? GetValue<T>() { return default; }

So, can you guess the output of the following code:

~csharp
Console.WriteLine(GetValue<string>());
Console.WriteLine(GetValue<int>());
Console.WriteLine(GetValue<int?>());

The first line outputs nothing, which makes sense: GetValue<string> returns a string? value, which really at IL code / CLR level is a string, and the default value is null.

The second line outputs... zero. How come? The reason is, even in version 9 C# cannot do miracle and return both T and Nullable<T>. The method is being called with T being int, so it returns default(int) i.e. zero, as T. So, even though the code now compiles, it does not exactly produces what we would expect (null). In fact, the method cannot return a null value type.

The third line outputs nothing. GetValue<int?> returns a... int?? value, I guess, which really is a int? with the second ? being discarded because int? is a value type. But in this case, the method is being called with T being int?, so it returns default(int?) i.e. null, as T (again), which happens to be int?, so we get a null value type. Are you still with me?

So what?

In most cases you will ignore all this and happily use nullable values here and there without issues. Just remember that nullable values and null references, though sharing a very similar syntax, are not exactly the same thing. And, come back and read again this post the day you will get this very odd behavior that you do not quite understand!

CSharp FIXME Code Comments

sgay@pilotine.com — Tue, 16 Mar 2021 09:20:00 Z

When working on code, I sometime can get deep in "the zone", a creative state where ideas keep flowing and I start refactoring things all around the code base, making quick and dirty changes here and there just to be able to go where I know I want to go. This is accumulating technical debt, and as with any debt, I believe that it can be a good thing, as long as it lets me achieve my goal and there is a reliable plan to repay that debt eventually.

Part of that process requires that that debt can be made highly visible. I love to drop "FIXME comments" in my code for that purpose.

public void MyMethod()
{
    // get a value and use it
    // FIXME this may throw and then we should handle it
    var s = GetSomething();
    
    UseTheValue(s);
}

ReSharper is nice enough to color these comments, and tag them in the scrollbar.

ReSharper also provides a useful To-to explorer which provides an overview of all these comments, with a way to easily navigate to each of them.

However... dealing with these FIXMEs remain a proactive and somewhat tedious task, and it is quite easy to forget about it, especially if one is prone to procrastination... leading to inevitable debt accumulation.

Show me FIXMEs

I am trying to address this situation via Roslyn Code Analysis. I have created a Comments Build Analyzer (available on NuGet with source code on GitHub) which detects FIXME comments, and creates corresponding warnings that show in the Error List pane.

At the moment, FIXME comment are reported with code ZB1001 and FIXME! (note the bang) comments are reported with code ZB1002. All you have to do is install the NuGet package in your project.

Combine this with .editorconfig files, and it becomes even more (painful?) useful. It is possible to use configuration-dependent .editorconfig files by registering them in the .csproj file.

<ItemGroup Condition="'$(Configuration)'=='Debug'">
    <EditorConfigFiles Include="debug.editorconfig" Link=".editorconfig"/>
</ItemGroup>

<ItemGroup Condition="'$(Configuration)'=='Release'">
      <EditorConfigFiles Include="release.editorconfig" Link=".editorconfig"/>
</ItemGroup>

Now, if debug.editorconfig contains:

dotnet_diagnostic.ZB1002.severity = warning # FIXME!

While release.editorconfig contains:

dotnet_diagnostic.ZB1002.severity = error # FIXME!

The FIXME! comments will raise warnings in the Debug build (so they will not prevent you from developing and building and testing, as #error statements would), and will raise errors in the Release build—and thus fail it.

The end result being that, with a properly configured CI, the build would break in case you ever leak a FIXME! comment. I still need to use it for some time and evaluate whether this is really useful,or just fancy, but so far it makes me feel safer.

Optimizing CSharp Null-Coalescing Operator

sgay@pilotine.com — Sat, 21 Nov 2020 13:05:00 Z

Consider the following code:

public Func<int> F { get; set; }

private int GetValue()
{
    // return the value produced by F, 
    // if F is not null, else zero
}

I naïvely implemented the function as:

if (F == null) return default;
return F();

Does the job.

Elegant Code

Yet, ReSharper squiggled the if statement, suggesting I might want to convert to:

return F == null ? default : F();

Which is nice indeed. Ah, ReSharper now squiggles the == null statement, suggesting I merge the conditional expression into:

return F?.Invoke() ?? default;

And... I started to wonder. It certainly is more compact. But is it cleaner? It reminds me of a recent thead initiated by Frans, on the topic of C# getting more and more syntax-complex, to the point that C++ looks elegant and you need ReSharper to remind you of all the new bells and whistles.

Thank you, but no. Obfuscation can sure be fun, but one day I might have to troubleshoot that code, and I do prefer the ?: pattern over the ?.Invoke ?? one. As Steve replied:

It's just obfuscating the intent of your code. Clarity over minimal keystrokes. I gotta support this code for years.

(rant) Every developer should have to spend some time doing 24/7 support on production-critical code. Once you have been waken up at 3am to spend hours trying to figure out what is wrong with some recent code changes while the entire factory waits for you to restart operations... you get a different idea of what elegant code is. (/rant)

Anyways.

And besides, it is not the same!

At that point I got a carried on by my rant, and started to think:

With the ?. pattern, if the function is null, we return the value type default value, else execute the function and return the value type result
With the ?.Invoke ?? pattern, if the function is null, ?.Invoke will be null i.e. a reference type, so there has to be some boxing and unboxing happening under the hood for the ?? operator to work

And so, the ?.Invoke ?? pattern has to be worse, performance-wise!

Time to turn to Sharplab.io. This amazing tool let you type C# code on the left, and presents you with the resulting IL or assembly code on the right:

We are going to compile the following code:

public Func<int> F { get; set; }
    
public int M1() 
{
    return F == null
        ? 0
        : F();
}
    
public int M2() 
{
    return F?.Invoke() ?? 0;
}

For M1 the IL code (in Release mode) is:

IL_0000: ldarg.0
IL_0001: call instance class [System.Private.CoreLib]System.Func`1<int32> C::get_F()
IL_0006: brfalse.s IL_0014

IL_0008: ldarg.0
IL_0009: call instance class [System.Private.CoreLib]System.Func`1<int32> C::get_F()
IL_000e: callvirt instance !0 class [System.Private.CoreLib]System.Func`1<int32>::Invoke()
IL_0013: ret

IL_0014: ldc.i4.0
IL_0015: ret

And for M2:

IL_0000: ldarg.0
IL_0001: call instance class [System.Private.CoreLib]System.Func`1<int32> C::get_F()
IL_0006: dup
IL_0007: brtrue.s IL_000c

IL_0009: pop
IL_000a: ldc.i4.0
IL_000b: ret

IL_000c: callvirt instance !0 class [System.Private.CoreLib]System.Func`1<int32>::Invoke()
IL_0011: ret

First, note that the ?. coalesce operator does not imply any kind of boxing, as I originally thought. So it is safe. In fact, the code produced for M2 looks simpler, especially with M1 invoking get_F() twice in case F is not null. However, remember this is only IL code. There is another level of optimization in the JIT, which leads to the following x86 assembly code:

C.M1()
    L0000: mov eax, [ecx+4]
    L0003: test eax, eax
    L0005: je short L000e
    L0007: mov ecx, [eax+4]
    L000a: call dword ptr [eax+0xc]
    L000d: ret
    L000e: xor eax, eax
    L0010: ret

C.M2()
    L0000: mov edx, [ecx+4]
    L0003: test edx, edx
    L0005: jne short L000a
    L0007: xor eax, eax
    L0009: ret
    L000a: mov ecx, [edx+4]
    L000d: call dword ptr [edx+0xc]
    L0010: ret

In other words, both methods end up doing almost exactly the same, at assembly level. And benchmarks (see below, if you really are into this) show that they perform the same. This is a good thing: it means that one can use one syntax or the other, without worrying about performance.

As for code elegance, I know what I prefer.

Appendix

This is more details, for people who are into it.

Just to be sure, I have benchmarked the two methods. The BenchmarkDotNet code is quite simple (see this Gist) and I have executed it with F being null, or returning a constant, or computing a value... and, funny enough, I never get the exact same duration for both methods, and one or the other is always randomly slightly faster that the other. I guess that is due to glitches on my benchmark machine, and it means that the methods are equivalent.

Just to be super sure, I fired WinDBG at the benchmark, after it had run. First you want to locate the class:

> !name2ee Benchmarks!Benchmarks.NullCoalesce
Module:      00007ff98a5cf800
Assembly:    Benchmarks.dll
Token:       0000000002000005
MethodTable: 00007ff98a69ea80
EEClass:     00007ff98a689038
Name:        Benchmarks.NullCoalesce

Then you want to dump the method table:

> !dumpmt -md 00007ff98a69ea80
EEClass:         00007ff98a689038
Module:          00007ff98a5cf800
Name:            Benchmarks.NullCoalesce
mdToken:         0000000002000005
File:            D:\d\Benchmarks\bin\Release\netcoreapp3.1\Benchmarks.dll
BaseSize:        0x20
ComponentSize:   0x0
Slots in VTable: 11
Number of IFaces in IFaceMap: 0
--------------------------------------
MethodDesc Table
           Entry       MethodDesc    JIT Name
00007FF98A520090 00007ff98a4f0a80   NONE System.Object.Finalize()
00007FF98A520098 00007ff98a4f0a90   NONE System.Object.ToString()
00007FF98A5200A0 00007ff98a4f0aa0    JIT System.Object.Equals(System.Object)
00007FF98A5200B8 00007ff98a4f0ae0    JIT System.Object.GetHashCode()
00007FF98A538F30 00007ff98a69e9f8   NONE Hazelcast.Benchmarks.NullCoalesce..ctor()
00007FF98A538F20 00007ff98a69e9c8    JIT Benchmarks.NullCoalesce.get_F()
00007FF98A538F28 00007ff98a69e9e0   NONE Benchmarks.NullCoalesce.set_F(System.Func`1)
00007FF98A538F38 00007ff98a69ea08    JIT Benchmarks.NullCoalesce.BenchmarkM1()
00007FF98A538F40 00007ff98a69ea20    JIT Benchmarks.NullCoalesce.M1()
00007FF98A538F48 00007ff98a69ea38    JIT Benchmarks.NullCoalesce.BenchmarkM2()
00007FF98A538F50 00007ff98a69ea50    JIT Benchmarks.NullCoalesce.M2()

And... !dumpil can show us the IL code, but we really want the assembly code:

> !u 00007ff98a69ea20
Normal JIT generated code
Benchmarks.NullCoalesce.M1()
Begin 00007FF98AAB5F20, size 17
00007ff9`8aab5f20 488b4108        mov     rax,qword ptr [rcx+8]
00007ff9`8aab5f24 4885c0          test    rax,rax
00007ff9`8aab5f27 740b            je      00007ff9`8aab5f34
00007ff9`8aab5f29 488b4808        mov     rcx,qword ptr [rax+8]
00007ff9`8aab5f2d 488b4018        mov     rax,qword ptr [rax+18h]
00007ff9`8aab5f31 48ffe0          jmp     rax
00007ff9`8aab5f34 33c0            xor     eax,eax
00007ff9`8aab5f36 c3              ret

> !u 00007ff98a69ea50  
Normal JIT generated code
Benchmarks.NullCoalesce.M2()
Begin 00007FF98AAE4220, size 17
00007ff9`8aae4220 488b5108        mov     rdx,qword ptr [rcx+8]
00007ff9`8aae4224 4885d2          test    rdx,rdx
00007ff9`8aae4227 7503            jne     00007ff9`8aae422c
00007ff9`8aae4229 33c0            xor     eax,eax
00007ff9`8aae422b c3              ret
00007ff9`8aae422c 488b4a08        mov     rcx,qword ptr [rdx+8]
00007ff9`8aae4230 488b4218        mov     rax,qword ptr [rdx+18h]
00007ff9`8aae4234 48ffe0          jmp     rax

My .NET host (.NET Core 3.1.9) produces assembly code that is slightly different from what Sharplab.io shows, but the conclusion stands: both methods are, practically, equivalent.

Optimizing CSharp Value Types

sgay@pilotine.com — Wed, 10 Jun 2020 16:00:00 Z

In a Twitter exchange with my friend James, we recently wondered how to properly document methods that return named value tuples. Why would we have to deal with methods returning value tuples? Well, consider this classic method:

public bool TryGetValue(TKey key, out TValue value) { ... }

Enters async. Ideally, we want:

public async ValueTask<bool> TryGetValue(TKey key, out TValue value) { ... }

But... async does support out parameters. And thus, the method logically becomes:

public async ValueTask<(bool, TValue)> TryGetValue(TKey key) { ... }

Which leads us to the original question: how would you document such a method?

/// <summary>Tries to get a value.</summary>
/// <param name="key">A key.</param>
/// <returns> ???? </returns>
public async ValueTask<(bool, TValue)> TryGetValue(TKey key) { ... }

The subject is not exactly new as Roslyn issue #13216 or CSharp issue #145 already explored more or less convoluted solutions in 2016. And somewhere in these issues, one can read:

"tuples really aren't well suited for public APIs or scenarios where you'd need or want to document them"

With the recommendation to use a record of some sort to return results. Which quite probably means returning a struct or even a class... and this is obviously going to cause some allocations, overhead etc.

Let us say, for the sake of the argument, that we refactor the method as:

/// <summary>Tries to get a value.</summary>
/// <param name="key">A key.</param>
/// <returns>A attempt at getting the value for the specified key.</returns>
public async ValueTask<Attempt<TValue>> TryGetValue(TKey key) { ... }

With Attempt<T> defined as:

public struct Attempt<T>
{
    public bool Success { get; set; }
    public T Value { get; set; }
}

So now, we are going to allocate an instance of Attempt<T> each time we return, and then use the property getters (i.e. invoke a method) to figure out whether the attempt was successful, and retrieve the value it carries.

How bad is it? Just to be sure, I have used SharpLab to show me the generated IL and assembly code for the following methods:

public void InvokeWithTuple()
{
    var (success, value) = TryGetValueWithTuple("foo");
    if (success) Console.WriteLine(value);
}

public void InvokeWithAttempt()
{
    var attempt = TryGetValueWithAttempt("foo");
    if (attempt.Success) Console.WriteLine(attempt.Value);
}

This is the assembly code generated for the tuple version (in Release mode):

L0000: push ebp
L0001: mov ebp, esp
L0003: sub esp, 8
L0006: xor eax, eax
L0008: mov [ebp-8], eax
L000b: mov [ebp-4], eax
L000e: push 1
L0010: lea edx, [ebp-8]
L0013: call C.TryGetValueWithTuple(Boolean)
L0018: mov ecx, [ebp-4]
L001b: movzx ecx, cl
L001e: mov eax, [ebp-8]
L0021: test ecx, ecx
L0023: je short L002c
L0025: mov ecx, eax
L0027: call System.Console.WriteLine(System.String)
L002c: mov esp, ebp
L002e: pop ebp
L002f: ret

And now, the assembly code generated for the Attempt version:

L0000: push ebp
L0001: mov ebp, esp
L0003: sub esp, 8
L0006: xor eax, eax
L0008: mov [ebp-8], eax
L000b: mov [ebp-4], eax
L000e: push 1
L0010: lea edx, [ebp-8]
L0013: call C.TryGetValueWithAttempt(Boolean)
L0018: cmp byte ptr [ebp-4], 0
L001c: je short L0026
L001e: mov ecx, [ebp-8]
L0021: call System.Console.WriteLine(System.String)
L0026: mov esp, ebp
L0028: pop ebp
L0029: ret

Can you spot the difference? Me neither. But... let us say you are quite fond of the var (success, value) = syntax. Can we still have it with attempts? Yes, with deconstruction:

public struct Attempt<T>
{
    public bool Success { get; set; }
    public T Value { get; set; }

    public void Deconstruct(out bool success, out T value)
    {
        success = Success;
        value = Value;
    }
}

And then, this is valid code:

var (success, value) = TryGetValueWithAttempt("foo");

But this involves deconstruction... it has to be more expensive, right? I will spare you the assembly code, it is exactly the same. The C# compiler and CLR jitter figure the deconstruction out for you.

There is one lesson here: the C# compiler and the CLR jitter are quite clever, and you probably want to understand how they work before implementing pointless optimizations. When in doubt, just write clean code.

What Becomes Of Models Builder

sgay@pilotine.com — Wed, 15 Apr 2020 14:55:00 Z

Models Builder is an Umbraco extension that generates C# strongly-typed class models for Umbraco content item. It allows developers to write @Model.Title in views instead of the more verbose @Model.Value<string>("title"). Models can be enriched and tweaked to greatly simplify the developement of sites.

It was originally created in 2013 by me, Stephan, and distributed as an independent NuGet package named "Zbu.ModelsBuilder". Then, around 2016, it was considered sufficiently important to be bundled with the Umbraco CMS official distribution. On that occasion, it was renamed "Umbraco.ModelsBuilder". I kept maintaining it as part of my HQ activity.

When I left HQ in 2019, I proposed to donate the project to HQ, but for various reasons that did not happen. Instead, HQ embedded a simplified version of Models Builder straight into Core—the one that currently ships with 8.x.

I, on the other hand, planned to grow and maintain the complete version, as "ZpqrtBnk.ModelsBuilder", and release long overdue features and fixes. I did start some work... and then got involved in other non-Umbraco projects, and lost both time and motivation. And then, nothing happened.

Models Builder Reloaded

Some people grew concerned that one tool they depend on would go abandoned. They reached out to me to discuss the future of Models Builder. It took me a bit of time to digest and accept that, despite all my good intentions, I was not able to do much... but here we are. It is about time to do something.

As of today, I am officially donating the project to the Umbraco Community. The project is now named "Our.ModelsBuilder". Its repository has moved to Our.ModelsBuilder on GitHub.

Models Builder Team

And how exactly is this different from abandonning the project? Well, the general idea is to form a team of maintainers so that the project does not depend on one single person. We need people to:

Understand how it all works and manage the product
Code
Maintain the documentation
Manage the release process, etc
(probably more?)

The good news is that, despite what people like to think, the project is not horribly complex rocket-science. It may require a bit of time to grasp, but then it is rather simple. It is essentially C# with very little UI. This, and I will happily join the team and make myself available to transfer whatever knowledge is required, and answer questions.

And thus, this is an official call for members. The temporay team is currently composed of myself, Frans de Jong and Dave Woestenborghs, and we obviously need more people.

This is a unique chance to have an impact on one of the most-used Umbraco tool. A unique opportunity that you certainly do not want to miss. Of course you are interested, so please contact one of us now, either in the comments of this post, or on the Community Slack, or on Twitter, or by email at our.modelsbuilder@gmail.com or by whatever means you feel adequate.

Do not waste time, the application closes on the 5th of May, at 05:05am.

Talk to you soon!

Three Fives Kit PCB Edition

sgay@pilotine.com — Thu, 19 Mar 2020 17:45:00 Z

Some time ago I built a Three Fives Kit from Evil Mad Scientist, and a quick circuit which blinked one LED with a real NE555 timer, and one with the kit.

This has been sitting on some shelve in my office ever since, but I have always wondered whether I could clean things up a little... maybe building a PCB for the circuit.

So, I asked on Twitter what people would use to design PCBs, and the always helpful and super-friendly maker Matt Brailsford from CircuitBeard suggested I tried KiCad.

Downloading and installing KiCab is relatively easy, but then I quickly hit a steep learning curve. I started reading tutorials... but was, to be honest, going nowhere. And then I found the Getting To Blinky 5.0 set of videos by Chris Gammel from Contextual Electronics. To make it short, these dense videos have everything you need, in amazing details.

I will not, therefore, explain KiCad here. Watch the videos. Let's just say that you will end up with a schema:

The schema has two blocks, each blinking a LED with a 555. There is a switch that can be used to select which capacitor to use, to produce either a 500Hz signal (that can be observed with a scope) or a .5Hz signal (to see the LED blink).

A bit more work takes you to the PCB design itself:

The top copper zones should make it easy to clamp the scope's crocodile plugs to observe signals, while the 555 areas will welcome chip sockets, allowing one to either plug a real 555, or the Three Fives Kit.

Next, the PCB needs to be manufactured. The recommendation was to go with OshPark which seems to have fewer options than, say, Jlc PCB or PCB Way— but that probably is a good thing as I could not understand most of these options anyways.

Delivery takes a bit of time, because the PCBs are manufactured by batches, but I eventually received this:

Finally, a bit of soldering takes us to the final state. The LED on the left blinks at 500Hz thanks to a true NE555 chip, and can be observed with the scope, while the LED on the right blinks at .5Hz thanks to the Three Five Kits.

Looks way cleaner in my office now.

French Developer Keyboard (2)

sgay@pilotine.com — Thu, 12 Mar 2020 14:05:00 Z

For years now, my main keyboard has been a black DasKeyboard. As in, totally black, no marking. Very much hype. It has allowed me to do cool things, such as remapping the layout to get a French developer keyboard.

My layout is a mix of Azerty (French) and Qwerty with characters such as curlies and brackets in convenient places. Makes programming way easier, is easy to learn, and not too different from what everyone uses—so it's not too hard to switch to and from other machines.

It always impresses people that I can type without having any marking on the keyboard. The blue Cherry MX switches make an amazingly loud noise... all in all, very cool. At least at the beginning. After a while, typing this very cryptic password without making mistakes reveals tricky, and don't mention the crazy noise.

In addition, having used my custom layout for about two years now, the positions have stabilized to the following layout, and I don't expect them to move anytime soon.

And so... I have finally ordered my own custom WASD keyboard. It has a very discreet marking, and quiter brown Cherry MX switches.

So far... I'm liking it a lot.

Umbraco Life Experiment: Feedback

sgay@pilotine.com — Tue, 29 Oct 2019 18:35:00 Z

A few weeks ago I started an experiment, and promised to be transparent about it, so... here is some feedback.

The ZpqrtBnk General License has received a few orders, totalling about 3% of its financing goal. Though other more significant participations have been considered, they will not turn into real orders.

What Happened?

A broad range of people discussed various topics, such as the value of the General License and what it could deliver, the outcomes of the recent Umbraco Community Roundtable, how "Umbraco has changed", the role of a community, and the general direction and agility of the CMS project.

To make it short, the consensus is that it would probably not be possible to achieve much in the current context. And that it may be time to acknowledge what we cannot change. As a usually discreet community member puts it, it may just be simpler to pretend everything is all right—and reconsider expectations and commitments.

The web publishing landscape is quickly evolving, new projects and new ways of building sites appear, new momentums form, safety may require diversification, life is too short, we all want to move forward, all those things.

What Does That Take Us?

I am now terminating the General License experiment. I will not issue licences, nor invoice anyone.

To all of you who have encouraged the experiment or raised concerns, offered perspectives, placed or considered orders or explained why you would not: a massive thank you, #h5yr. I owe you a lot, you truly are a community.

As far as ModelsBuilder or Umbraco are concerned, I am back to full Open Source mode which, as Bruce Perens states, is all about generosity¹. I will happily release new versions and contributions, if and when I have the time and motivation to do so.

❤︎

Be seeing U!

Yes, I am considering a Patreon or GitHub sponsorship to help finding time for Models Builder.↩

.NET Core 3.0 Release

sgay@pilotine.com — Mon, 23 Sep 2019 19:20:00 Z

This week is .NET Conf 2019, and as expected (after a suprise RC1), .NET Core 3.0 has been officially launched (see the announcement).

And what better way to celebrate, than to experiment with it?

Let the Fun Begin

This site now has a B-side, at b.zpqrtbnk.net. It runs on the same Windows server (just another IIS site) and the same database instance. It is, so far, a typical load-balanced scenario. It is powered by Umbraco... on AspNet Core 3.0, thanks to Beyumbe.

Beyumbe is an experimental / lab software layer that provides most of the .NET Core plumbing for Umbraco: bootstrapping the application, hosting, dependency injection, filesystems, logging, background-tasking, routing, etc.

Umbraco sits on top of this layer, pretty much unchanged, and provides the content cache, its pipeline and services, etc—everything that is required to publish content. It does run its distributed cache, for instance.

One of the benefits of running a pure .NET Core site, apart from the excitement, is that it can be turned into a Docker container. This site now also has a C-side (can you picture this?) at c.zpqrtbnk.net. It runs as a Linux Docker container on Amazon AWS Fargate service. It is also part of the load-balancing scenario, and updates with the other sides.

You might notice that this C-side does not render images. Fargate in a compute engine, which simply executes containers. It does not yet support mounting filesystems into containers, and this prevents us from sharing a common media directory. The feature is currently "in progress" at Amazon, yet with no ETA.

Azure does seem to support mounting Azure Files shares into Azure Containers, so it may be easier on Azure. Unfortunately, I don't really have time to experiment on both platforms at the moment.

Next?

Beyumbe needs some love and polish to be able to support Umbraco in a robust way, as the whole thing was put together in a very short time. But it is slowly getting there.

As for Umbraco itself, most of the Umbraco.Core project is ported, but work remain to deal with configuration, identity & security, and the runtime / maindom.

The Umbraco.Web project is an entirely different beast. Only the very basic minimum, required to render content, has been ported. Everything else, from trees to controllers, WebApi to healthchecks, you name it, needs to be ported.

Umbraco on .NET Core? Not fully there yet. But a nice project.

Umbraco Life Experiment

sgay@pilotine.com — Fri, 13 Sep 2019 19:00:00 Z

A few months ago I announced I would be leaving HQ and transitioning back to the community side of Umbraco, end of September. People assumed I had some sort of a Grand Plan, an amazing business idea—but the reality is more complex.

Let's say I wanted to be closer to community and client work, in order to contribute in a more direct and effective way on various tools, features and topics that have been lagging for some time. With the goal of helping Umbraco be a strong, reliable yet simple platform for pro & advanced users—and friendly, of course.

And... the roadmap was not much clearer than that.

Over the past 3 months, I have had numerous conversations with many members of the community, to find out what people valued and needed, and how they imagined these services could be delivered. Thanks to the thelp of those precious friends, I am now ready to introduce...

The Experiment

I should be looking for a new role (.NET/C#/architecture), really. At least that is what all my "entreprise" friends tell me. But before I do, I want to try something.

Services:

As of October 1st, I am immediately available for .NET work, as freelance. Umbraco, non-Umbraco, technical, less technical (I have spent a good deal of my life managing projects, too).

Umbraco-wise, I provide Architecture Guiding and Troubleshooting Guiding services. Here, guiding means working with you, advising and teaching, on real cases, to reach solutions. Per hour, or per day, and optionally on-site.

Software:

Models Builder, and any other tools I may release, remains open source, and free. They are distributed under the MIT license, but with a twist. If you use them in any way that allows you to make money, directly or indirectly, and/or if you expect any kind of support, you are morally required to purchase a...

ZpqrtBnk General License

Everything may be open, but I still need a way to secure an income. Therefore, much alike Poul-Henning Kamp's Varnish Moral License, I am introducing the ZpqrtBnk General License.

It works like this: you tell me that you want to purchase a license. You set your price. I send you an invoice from my company (official, proper company invoice, handling VAT numbers etc). You pay the invoice. You are on the list.

You then have the moral right to use the tools I release. You can expect them to be maintained, bugs to be fixed, questions to be answered, and feature requests to be considered.

In addition, you ensure that I can keep improving people's Umbraco and .NET lives, be it on the community Slack, on Our, at meetups and festivals, or by fixing bugs, implementing features, etc.

This is not a Make Money Fast scheme; the goal is to maintain my income. PHK is radical about it, and publishes his accounting status (eg, 2019). I don't know exactly how I will do it, but the plan is to be transparent too.

Browse to the ZpqrtBnk General License page for infos and FAQs. Or to the General License Questions for even more questions.

Ah, but...

This is never going to work. People don't pay for what they can have for free. Who do you think you are? If I need to pay I am going to build it myself! You cannot enforce your license anyways. You cannot make a living of it. Others have tried.

True. And reasons why the whole thing is an experiment. I am interested in seeing what happens, but I am not completely naïve. Sure, I want free, open-source software, sponsored by people who value it. I don't want to issue activation codes, or hear about developers having to use dotPeek to figure out issues in my private code, etc.

But, this: noone is getting anything for free. Either it works, or I have to stop and humbly move on to something else—no offense. It's as simple. It's an experiment, it's a real challenge for my impostor syndrome, but I want to at least try it.

Models Builder has a new milestone and work-in-progress: a new, autonomous version, adding features to the built-in version. But—that is only going to happen if my family can eat ;-)

Current balance is zero, and I have approximatively zero autonomy beyond October.

Let's see where this goes.

Umbraco 8.1.4 Breaking & Models Builder

sgay@pilotine.com — Wed, 04 Sep 2019 16:40:00 Z

UPDATED: the proposed workaround has been simplified, see at the bottom of this post.

The Umbraco 8.1.4 release fixes issue #6033 but introduces a breaking change.

Up until this release, when a media picker was configured to pick only images, the corresponding property value converter would report the property type as Image or IEnumerable<Image> and Models Builder would generate the property as (in MyModel.generated.cs):

public partial class MyModel
{
  // ...

  [ImplementPropertyType("myImage")]
  public Image MyImage
    => this.Value("myImage");

  [ImplementPropertyType("myImages")]
  public IEnumerable MyImages
    => this.Value>("myImages");
}

Thus allowing you to write:

Unfortunately, that was based on the assumption that, with this configuration, the media picker would only allow media of type "image" (or anything inheriting "image") to be picked. In reality, it seems that the media picker has different rules and allows various types of media to be picked.

As a consequence, users would see nasty YSODs when picking anything that would not inherit from "image", as it would of course not fit within an IEnumerable<Image>.

The fix that was introduced forces the property value converter to report the property type as IPublishedContent or IEnumerable<IPublishedContent> no matter what can be picked. Alas, that breaks the existing Models Builder properties. And, if you re-generate models, what was Image becomes IPublishedContent and you lose the direct access to properties such as width or height.

Workaround

However, assuming that you know that you are only going to pick images, you do not want to clutter your views with casts or non-strongly-typed property accesses.

The workaround to keep all your views unchanged and clean, consists in declaring your own implementations of these properties, in a partial class, alongside the existing models. Models Builder will detect them, and not generate anything. You want (in MyModel.cs):

public partial class MyModel
{
  [ImplementPropertyType("myImage")]
  public Image MyImage
    => this.Value("myImage") as Image;

  [ImplementPropertyType("myImages")]
  public IEnumerable MyImages
    => this.Value>("myImages")
           .OfType();
}

This can be tedious, though, if you have a lot of models.

Workaround (2)

UPDATE: This workaround works but is too complex, for no reason. Read it, then see the next workaround for the simple solution.

Alternatively, there is a more radical approach, if you are brave enough. Get the code for MediaPickerValueConverter from 8.1.3, drop it into your own solution, and use a composer to use it in place of the one that ships with 8.1.4:

using UmbracoConverters = Umbraco.Web.PropertyEditors.ValueConverters;

public void Compose(Composition composition)
{
  composition.PropertyValueConverters()
    .Remove()
    .Append()
}

Everything will be back to normal, and that is probably what I am going to do on this site. But then of course, you end up running with a non-standard converter.

Workaround (3)

Same as above, get the code for MediaPickerValueConverter from 8.1.3, drop it into your own solution, and make sure you remove its [DefaultPropertyValueConverter]. That's it. No need for a composer. Since your converter is not "default", it will override the default one.

And, even better, you can use the converter posted by Ronald in this comment on the original GitHub issue. It tries to mitigate the issue in a nice way.

I am afraid there is no ideal, immediate solution. In a perfect world... the media picker should be fixed, so one can indicate a (base) type to be picked, and so that only media of that type can be picked...

Missing Folders in Umbraco Tree

sgay@pilotine.com — Fri, 30 Aug 2019 14:55:00 Z

On this very site, which originally started as a v7 site and has slowly been upgraded to the latest 8.1 release, something weird started happening. Some media folders stopped showing in the media tree left), although they would still show in the media panel (right).

So: the media folders still existed, but they just did not show in trees.

I am pretty sure it worked with 8.0, and stopped working with 8.1. Which is strange, as the original issue seems to target the 7-to-8 upgrade. Anyways. I just wanted to share the cause, and the fix.

The cause is missing rows in the umbracoMediaVersion table for these folders. The fix consists in inserting these missing rows again.

This is exactly what the following SQL does:

insert into umbracoMediaVersion (id, path)
select VersionId, NULL
from (

	select n.id NodeId, n.Text Name, ct.alias Alias, cv.id VersionId, mv.id MvId, mv.path MvPath
	from umbracoNode n
	join umbracoContent c on n.id=c.nodeId
	join cmsContentType ct on c.contentTypeId=ct.nodeId
	join umbracoContentVersion cv on n.id=cv.nodeId
	left outer join umbracoMediaVersion mv on cv.id=mv.id
	where n.nodeObjectType='B796F64C-1F99-4FFB-B886-4BF4BC011A9C'

	and ct.alias='Folder' -- only folders
	and mv.id is null -- that dont have the required row
) x

Note that you may want to run the inner query first, just to verify that your database is indeed missing these rows.

Models Builder Extension

sgay@pilotine.com — Fri, 19 Jul 2019 09:51:01 Z

One way to generate models for Umbraco with the Models Builder tool has long been to use the Visual Studio Custom Tool. This extension provides a Single File Generator which can be used just as any standard Visual Studio Custom Tool.

Meanwhile, Microsoft has introduced .NET Core and is slowly evolving the structure of its Visual Studio projects, and updating the tooling along the way. Let us say that the road is, sometimes, a bit unclear and hard to follow.

Using a single file generator to generate multiple files has traditionally been "the way" to do it, but it has also always been hackish, and as this issue and others made obvious. It is becoming harder and harder to support with the new "NET.Sdk" project types.

I am, therefore, sad to announce that the Custom Tool is now dead. But do not despair! It is superceeded by the Extension, which, essentially, provides exactly the same service, in a slightly different way.

Migrating

In order to migrate to the extension, first uninstall the Custom Tool extension, then install the Extension.

Then, the only difference is that models are not generated under a C# file anymore, but under a special placeholder. You probably don't need the root C# file anymore, unless it contained attributes to configure models. The next section will explain it all.

The configuration (in Tools | Options) remain the same.

Using the extension

Right-click on the folder containing your models, both the generated and non-generated partials. Select Add | New item....

Select Visual C#, Umbraco, and add a new Umbraco Models placeholder named, for instance, Models.mb. The name is of no importance, only the extension is.

Now, right-click on that new Models.mb file and select Build Models.

The extension connects to the running site, retrieves models, and adds them to the project, nicely nested under the models placeholder.

Configuring

By default, models are generated in a namespace derived from the root namespace of the project, and the folders structure. That, and various other aspects of models, can be configured via attributes.

Add a file Models.cs (or any other name, as long as it is a C# file) to the models folder, containing the following code (it does not need to contain a class definition!):

using Umbraco.ModelsBuilder;

[assembly:ModelsNamespace("MyOwnNamespace")]

That file will be parsed, and models will be generated in MyOwnNamespace.

Refer to the (kinda obsolete, soon to be updated) documentation for more attributes.

What's Next?

As mentioned above, the documentation is kinda obsolete. There are tons of things that can be configured, and noone is aware of it. Next effort will be to cleanup the documentation, and implement some long-requested features.

Stay tuned!

SolutionBook for Visual Studio 2019

sgay@pilotine.com — Thu, 20 Jun 2019 12:10:00 Z

For many years, I have used the excellent SolutionStartPage extension for Visual Studio 2015 and 2017. This extension replaces the default Start Page with a customizable view of all my solutions. It is like a giant start menu: fire Visual Studio, pick the solution you want to work on.

Alas, Visual Studio 2019 has replaced the start page with an entirely different start window, which cannot really be modified, entirely breaking SolutionStartPage (see issue #25). There are a few discussions about the future of the start page on Visual Studio's developper community (see for instance this one) but it does not seem that Microsoft is going to address the situation anytime soon.

And, this makes working with Visual Studio 2019 way more annoying. I was really used to just firing Visual Studio and opening a frequently-used solution, without having to think about where it is on my disk.

Problem → Solution

So... I spent a couple of evenings putting together a replacement for Visual Studio 2019, and... SolutionBook is now available on the Visual Studio MarketPlace with code in its own GitHub repository.

This extension installs a new Visual Studio tool window, which can be displayed with View | Other Windows | SolutionBook, and docked anywhere—I dock mine to the left, with the already existing Toolbox tool window.

It lets you organize your solutions in a tree. It's always there when Visual Studio opens, and double-clicking a solution just opens it. You can add and remove solutions, move them around, group them in folders, etc. That is all. It saves me tons of time. YMMV.

Note: you have to save your changes using the toolbar button. Saving is not automatic. And it won't tell you if you forget. And the Refresh toolbar buttons reloads from disk. This is how concurrency between multiple Visual Studio instances is (not) managed.

Another note: this was all quickly put together. WPF is fantastic but also hard. There may be issues, and it's probably not the cleanest code I have produced. Saving and refreshing should be all automagic. Feel free to contribute!

Enjoy!