Table of Contents

Examples

Four complete programs in the repository's samples/ folder, each the kind of project you would actually write with AsmSdk. Each page walks through one: the project file, the assembly that matters, and how the result is tested. Every fact these pages state is checked by AsmSdk's own end-to-end tests (ExampleTests).

Example What it is What it shows
Crc32C CRC-32C (the iSCSI, ext4 and gRPC checksum) as a freestanding shared library for seven RIDs, called from C# one x64 source for Windows, Linux and macOS through asmsdk.inc, an ARM64 source in GNU syntax, ExportsFile, run-time CPU dispatch on each OS, constants computed by the assemblers, a 3-way kernel (SSE4.2 + PCLMULQDQ, CRC32 + PMULL), [LibraryImport] with SuppressGCTransition
Shipping to .NET through NuGet Crc32C as two packages, and a .NET program that uses them by version a native package with runtimes/<rid>/native/ for seven RIDs, a managed package that depends on it, a consumer that never mentions assembly
Testing and measuring from C# Crc32C's xunit tests and BenchmarkDotNet benchmark every code path against a C# reference, a deliberately broken constant caught, timings against BitOperations.Crc32C
WordCount wc in assembly, on glibc (linux-x64) open, read and printf through the PLT, a libc data object through the GOT, AsmLibcSymbol, two sources sharing a record, SSE2 counting
HexDump xxd in assembly, with no libc at all (linux-x64) _start, raw system calls, interrupted calls and short writes handled, a static executable of about 4 KB

The smaller Hello.* samples are still the place to start: Getting started builds the same kinds of project in a few lines each, and Samples lists them all.

A C# gRPC service on an engine in assembly

GrpcAsm, built with AsmSdk, is a gRPC server whose HTTP/2, HPACK, gRPC and event loops are x86-64 assembly (Linux). It hosts ordinary grpc-dotnet service classes, the ones ASP.NET Core maps with MapGrpcService<T>(), with one line:

Greeter.BindService(server.ServiceBinder, new GreeterService());

Its samples/GreeterNet and samples/GreeterAspNet host the same classes on GrpcAsm and on ASP.NET Core gRPC, and a measurement in 12 paired rounds compares them. On four vCPUs with both servers saturated, a ~1 KiB order is served at 4.0 times the calls per second, at 4.0 times less CPU per call. On SayHello, where the server's own work dominates, the CPU per call is 12 times lower. That page also covers latency, memory, one vCPU, and what GrpcAsm does not do yet.

Building and running them

The samples build against the SDK of the checkout they are in: the end-to-end tests pack it into a local feed first, then build and check every sample.

git clone https://github.com/AsmFoundation/AsmSdk && cd AsmSdk
dotnet run toolchain/fetch.cs -- --rid linux-x64                 # or win-x64, win-arm64, linux-arm64, osx-arm64
dotnet test --project tests/AsmSdk.Tests/AsmSdk.Tests.csproj     # packs, builds every sample, checks them

After that, the outputs are under each sample's bin/Release/<target framework>/<rid>/. Crc32C's C# programs run on any of its seven platforms. WordCount and HexDump are Linux x64 programs: on Windows, run them in WSL or in a container.

To use a sample in your own repository, copy its folder (for Crc32C, the four Crc32C* folders together) next to a global.json that names the SDK:

{ "msbuild-sdks": { "AsmFoundation.Sdk": "0.3.0" } }

They need nothing else from the AsmSdk repository: restore gets the SDK and its toolchain from nuget.org.

How they are checked

ExampleTests runs on every push, on the five build machines. Crc32C's C# programs run on each of them, with that machine's own build; the Linux x64 programs run on the Linux x64 one:

  • Crc32C: the exact list of exported names and their version, the constants NASM computed, both package layouts (seven RIDs) and the dependency between them, the library's own 21 unit tests, the benchmark's self-check, and the NuGet consumer's output.
  • WordCount: what it imports from glibc, its counts against a C# count of the same files (including a word that spans two reads), and its error messages and exit statuses.
  • HexDump: that it is static and under 8 KB, its output against a C# rendering of xxd's format, and its errors. It was also compared with xxd itself, byte for byte.