What is a Plug?

Plugs are pieces of code that replace functionality provided Windows or a native code DLL to a .NET library. Not all “holes” have been filled, and we plug them as needed. So if you see a Missing plug error, it means you are trying to access something that has not yet been “plugged”.

What can I do about missing plugs?

See Missing Plugs

Intro to Plugs

Original article written by Kudzu


This article will demonstrate how to implement .NET code that relies on Windows APIs or internal calls in Cosmos. In addition, it will cover how to interface directly to the hardware using Cosmos and assembly or X#.

What is Cosmos?

Cosmos is an Operating System development kit (more info) which uses Visual Studio as its development environment. Despite C# in the name, any .NET based language can be used including VB.NET, Fortran, Delphi Prism, IronPython, F#, and more. Cosmos itself and the kernel routines are primarily written in C#, and thus the Cosmos name. Besides that, NOSMOS (.NET Open Source Managed Operating System) sounds stupid.

Cosmos is not an Operating System in the traditional sense, but instead it is an “Operating System Kit”, or as I like to say “Operating System Legos”. Cosmos lets you create Operating Systems just as Visual Studio and C# normally let you create applications. Most users can write and boot their own Operating System in just a few minutes, all using Visual Studio. Cosmos supports integrated project types in Visual Studio, and an integrated debugger, breakpoints, watches, and more. You can debug your Operating System the same way that you debug a normal C# or VB.NET application.

The Need For Plugs

Plugs are needed in three scenarios in Cosmos:

  1. Internal Calls
  2. PInvoke
  3. Direct Assembly

Internal Calls and PInvoke

Some methods in .NET classes are implemented without using .NET code. They are implemented using native code. There are two reasons for this:

  1. The method relies on the Windows API (PInvoke).
  2. The method relies on highly optimized C++ or assembly (internal calls) which exist in the .NET runtime.

PInvoke is used to draw to the screen, access existing Windows encryption APIs, access networking, and other similar functions.

Internal Calls (icalls) are used for classes which require direct access to the .NET runtime. Examples are classes which need to access memory management, or in some cases for raw speed. The Math.Pow method uses an internal call.

Plugs can be written in C# (or any .NET language), or assembly.

Direct Assembly

To talk to hardware, Cosmos must be able to interact with the PCI bus, CPU IO Bus, memory, and more. Memory can usually be accessed using unsafe pointers; however, in other cases, the assembly code must be handwritten. Plugs can be used to interface C# to assembly code directly, making the assembly calls callable as if normal C# code is being called.

Writing X86 Assembly in Cosmos

An X86 assembly can be written in Cosmos using classes:

But Cosmos also supports a higher level abstraction called X#. X# is a typesafe assembly language which maps to X86 assembly. X# looks like this:

Writing Plugs

To write a plug, first we must decide the target of our plug. For example, Math.Abs(double) is implemented as an internal call.

If you try to call it in Cosmos without a plug, the compiler will produce an error, “plug needed”, because there is no IL code in it for IL2CPU to compile X86. So the “plug needed” error means that you have used some method which relies on an internal call or PInvoke, and thus Cosmos cannot compile it.

In the case of Math.Pow, it will work because the Cosmos kernel already includes a plug which is automatically used.

The plug is used by the compiler at runtime to substitute code. Instead of performing an internal call or Windows API which is impossible for Cosmos because it is not running under the CLR or Windows, the replacement code supplied by the plug is inserted and used. It is a form of forced inlining and replacement.

To create the plug, we need to create a new class. Plugs in the kernel are kept in separate assemblies and referenced by the kernel. This allows IL2CPU to include and use the plugs.

Plug classes can contain more than one method, although this excerpt only shows one. The Plug attribute is the key item in this example. It tells IL2CPU that this class is used to replace methods of the System.Math class. It then proceeds to find methods to match against the methods in System.Math.

Direct Assembly Plugs

Direct assembly plugs are used to allow C# to interface directly to X86 assembly code. An example of this is the IOPort class which allows device drivers to directly access the CPU bus which is required to talk to many hardware devices.

First, an empty class written partially in C# is created. Methods that will be plugged by the assembly are created empty. However, if they are not of return type void, a dummy value must be returned so that the C# compiler will compile it. The return value however will not be used, because plugs cause the target method’s implementation to be ignored and the plug’s implementation to be used instead.

As you can see, the Write methods are empty, but the Read methods require a dummy value.

The class is then plugged using this code:

Note that the code in this case is not written in X#. Many of our older plugs are still written in the older syntax.

Now that we have a plug, we can access the IOPort class directly in C# code. This example is from the ATA (Hard disk) class.

Another Plug Example

In the BCL, the Console class calls several internal methods which finally end up in Windows API calls. We don’t need to plug only the methods that directly map to Windows API calls, but instead we plug methods much higher up the tree and completely replace the implementation to call our TextScreen class instead.