Visual Basic kernels
In this article, we will discuss writing a Cosmos Gen3 kernel in Visual Basic: creating the project, the kernel class, the members that take a span, and the classes that are written in C#.
A Visual Basic kernel is built like a C# one. Its .vbproj uses the same Cosmos.Sdk and takes the same feature switches, cosmos build turns it into a bootable ISO for x64 or ARM64, and cosmos run boots that ISO in QEMU. What differs comes from the language: Visual Basic cannot declare a Span(Of T) or a ReadOnlySpan(Of T). A Visual Basic kernel still calls the members that take one, but the few classes whose own members take one are written in C#.
| C# | Visual Basic | |
|---|---|---|
| Created with | cosmos new MyKernel |
cosmos new MyKernel -l vb |
| Project file | MyKernel.csproj |
MyKernel.vbproj |
| Kernel class in | Kernel.cs |
Kernel.vb |
| Calls a member that takes a span | Yes | Yes, with a String or an array |
| Declares a member that takes or returns a span | Yes | No, a build error (BC30668) |
If you find bugs or something abnormal, please submit an issue on our repository.
Creating the kernel
cosmos new creates a kernel project in a folder named after it. Its -l option picks the language, csharp (the default) or vb, and the commands that build and run the kernel are the same in both:
cosmos new MyKernel -l vb
cd MyKernel
cosmos build
cosmos run
The Cosmos extensions for VS Code, Visual Studio and Rider (IDE Extensions) ask for the language when they create a kernel.
The folder holds what a C# kernel's folder holds, with MyKernel.vbproj and Kernel.vb in place of MyKernel.csproj and Kernel.cs. A property that another article of this guide sets in the .csproj, a feature switch for instance, goes in the .vbproj and is written the same way. This one leaves the network stack out of the kernel:
<PropertyGroup>
<CosmosEnableNetwork>false</CosmosEnableNetwork>
</PropertyGroup>
The kernel class
Kernel.vb holds the kernel class. It derives from Cosmos.Kernel.System.Kernel and overrides BeforeRun and Run, as the C# kernel of Kernel Startup does:
Imports Sys = Cosmos.Kernel.System
Public Class Kernel
Inherits Sys.Kernel
Protected Overrides Sub BeforeRun()
Console.WriteLine("Cosmos booted successfully!")
End Sub
Protected Overrides Sub Run()
Console.Write("Input: ")
Dim input As String = Console.ReadLine()
Console.Write("Text typed: ")
Console.WriteLine(input)
End Sub
End Class
The class is declared outside any Namespace block, and that is what lets the SDK find it. The SDK looks for the kernel class under the name <RootNamespace>.Kernel, and Visual Basic places a class declared outside any block in the project's root namespace, which is the project's name: here the class is MyKernel.Kernel. A Namespace block is nested under the root namespace, so a class declared inside Namespace Boot is MyKernel.Boot.Kernel, and the build stops on BC30002: Type 'Global.MyKernel.Kernel' is not defined until the .vbproj names the class:
<PropertyGroup>
<CosmosKernelClass>MyKernel.Boot.Kernel</CosmosKernelClass>
</PropertyGroup>
The SDK also turns Option Strict on. A late-bound call, one made on an Object whose member Visual Basic looks up when the kernel runs, goes through reflection, which a kernel compiled ahead of time cannot count on, so the compiler refuses it at build time (BC30574).
Members that take a span
Some members of the Cosmos API, and of .NET, take a span: one overload of VfsManager.TryMount takes the mount source as a ReadOnlySpan(Of Char), and IBlockDevice.ReadBlock fills a Span(Of Byte). Call them with a String or an array and the compiler converts the argument, as in these two calls of the kernel at the end of this page, where "" is the mount source and sector a Byte array:
VfsManager.TryMount("ramfat", "", MountFlags.None, "/mnt", mount)
ramDisk.ReadBlock(0, 1, sector)
What Visual Basic cannot do is name the type. Span(Of T) and ReadOnlySpan(Of T) are ref structs, a kind of type the language does not support, and a parameter, a return type, a field or a local declared as one is a build error:
error BC30668: 'Span(Of Byte)' is obsolete: 'Types with embedded references are not supported in this version of your compiler.'.
Classes written in C#
Overriding or implementing a member means declaring its parameters, so a class cannot be written in Visual Basic when a member it must override or implement takes or returns a span. Among the classes this guide has you write, three are in that case:
| To write | The class declares | Described in |
|---|---|---|
| A disk of your own, such as a RAM disk | IBlockDevice.ReadBlock and IBlockDevice.WriteBlock |
Try it on a RAM disk |
| A sound computed as it is read | AudioStream.Read |
Generating sound |
| A driver | Driver.Matches |
Writing a Driver |
The interfaces a filesystem driver implements are in that case too, with members such as IFileOperations.Read.
Write such a class in a C# class library and reference the library from the kernel. For the RAM disk, run these three commands in the folder that holds MyKernel:
dotnet new classlib -lang "C#" -o MyKernel.Storage
dotnet add MyKernel.Storage package Cosmos.Kernel.HAL --version <version>
dotnet add MyKernel reference MyKernel.Storage
<version> is the version MyKernel.vbproj names in its Sdk="Cosmos.Sdk/..." attribute, so that the library and the kernel are compiled against the same Cosmos release. Cosmos.Kernel.HAL is the package that holds IBlockDevice; a class deriving from AudioStream needs Cosmos.Kernel.System instead, and a driver library is set up as A driver library describes, with the NoWarn line that acknowledges the experimental driver kit (COSMOS0003). Once a library sits beside the kernel, run cosmos update from the folder that holds both, where it finds the version of each project and moves the two together.
Replace the Class1.cs the template created with MemoryBlockDevice.cs. It is the class of Try it on a RAM disk, declared public so that the kernel sees it:
using Cosmos.Kernel.HAL.Devices.Storage;
namespace MyKernel.Storage;
public sealed class MemoryBlockDevice : IBlockDevice
{
private readonly byte[] _storage;
public MemoryBlockDevice(string name, ulong blockSize, ulong blockCount)
{
Name = name;
BlockSize = blockSize;
BlockCount = blockCount;
_storage = new byte[blockSize * blockCount];
}
public string Name { get; }
public ulong BlockSize { get; }
public ulong BlockCount { get; }
public void ReadBlock(ulong blockNo, ulong blockCount, Span<byte> data)
=> _storage.AsSpan((int)(blockNo * BlockSize), (int)(blockCount * BlockSize)).CopyTo(data);
public void WriteBlock(ulong blockNo, ulong blockCount, ReadOnlySpan<byte> data)
=> data.Slice(0, (int)(blockCount * BlockSize)).CopyTo(_storage.AsSpan((int)(blockNo * BlockSize)));
public void Flush() { }
}
The kernel creates the disk, formats it, mounts it and uses it through System.IO, passing a String or an array wherever a member takes a span:
Imports System.IO
Imports Cosmos.Kernel.System.FileSystem
Imports Cosmos.Kernel.System.FileSystem.Fat
Imports MyKernel.Storage
Imports Sys = Cosmos.Kernel.System
Public Class Kernel
Inherits Sys.Kernel
Protected Overrides Sub BeforeRun()
Dim ramDisk As New MemoryBlockDevice("RAMDISK", 512, 65536)
Dim fat As New FatFileSystemType(ramDisk)
Dim options As New FatFormatOptions With {.Type = FatType.Fat16}
Dim mount As VfsMount = Nothing
If Not VfsManager.RegisterFileSystem("ramfat", fat) OrElse
Not VfsManager.TryFormat("ramfat", "", options) OrElse
Not VfsManager.TryMount("ramfat", "", MountFlags.None, "/mnt", mount) Then
Console.WriteLine("RAM disk setup failed.")
Return
End If
File.WriteAllText("/mnt/hello.txt", "Hello from Visual Basic")
Console.WriteLine(File.ReadAllText("/mnt/hello.txt"))
Dim sector(511) As Byte
ramDisk.ReadBlock(0, 1, sector)
Console.WriteLine("Boot sector ends with " & sector(510).ToString("X2") & " " & sector(511).ToString("X2"))
End Sub
Protected Overrides Sub Run()
Sys.Power.Halt()
End Sub
End Class
The kernel prints the content of the file it wrote, then the two bytes that end a FAT boot sector, read straight from the disk:
Hello from Visual Basic
Boot sector ends with 55 AA
Summary
| Task | Call |
|---|---|
| Create a Visual Basic kernel | cosmos new MyKernel -l vb |
| Build and run it | cosmos build, cosmos run |
| Set a feature switch | <CosmosEnableNetwork>false</CosmosEnableNetwork> in the .vbproj |
Declare the kernel class inside a Namespace block |
<CosmosKernelClass>MyKernel.Boot.Kernel</CosmosKernelClass> in the .vbproj |
Pass text to a ReadOnlySpan(Of Char) parameter |
A String |
Pass a buffer to a Span(Of Byte) parameter |
A Byte array |
| Write a class that declares a span | A C# class library the kernel references |