API's that Suck

January 4, 2010

Learning IL – The Echo Program

Filed under: CIL — Grauenwolf @ 4:27 pm

The requirements for our echo program is pretty simple.

  1. Take any number of command line arguments.
  2. Print each argument on separate lines.
  3. Return the number of command line arguments.

In this lesson you will learn how to define parameters, work with arrays, work with loops, and return values from functions. This lesson assumes that you already understand the hello world code.

Version 1

Version 1 will deal with requirements 1 and 3. This will be enough to prove that the command line parameters are actually making it all the way to the program and the return value is making it back to the shell. In Windows you can use the command “ECHO %ERRORLEVEL%” immediately after running the program to see the return value. For this to work you need to run the program itself from the command line as well.

  1. .assembly extern mscorlib {}
  2. .assembly EchoProg {}
  3. .method static int32  Main(string[] args)
  4. {
  5.     .entrypoint
  6.     ldarg.0
  7.     ldlen
  8.     ret
  9. }

Line 1 is the core assembly reference. Again, I’m not asking for a specific version.

Line 2 is our program’s name. I’m calling it “EchoProg” because “echo” is reserved by the Windows command shell.

Line 3 is our entry point. Lets compare is to the hello world version.

  1. .method static void Main()

As you can see void has been replaced by the return type. In addition, we now have one argument in a C#-like style with the type preceding the argument name. Note that we don’t actually use the argument name anywhere, it is just their for reference.

Line 6 is the “load argument N onto the stack” command. In this case we are loading the “args” parameter, which is a pointer to an array of string.

Line 7 is the “replace the array on the stack with it’s length” command, also known as load length.

As I mentioned last time, the return command in line 8 takes the last value on the stack and places it on the calling stack, then exits the current function.

To make experimenting with this code a little easier, I wrote this little batch file. If you run it using version 1, you should get the number 4.

  1. ilasm EchoProg.il
  2. PEVerify EchoProg.exe
  3. EchoProg.exe "la la la" dee di doh

Version 2

Before we jump into loops, lets just try printing the first command line argument. The code for this is pretty straight forward.

  1. .assembly extern mscorlib {}
  2. .assembly EchoProg {}
  3. .method static int32  Main(string[] args)
  4. {
  5.     .entrypoint
  7.     //printline code
  8.     ldarg.0
  9.     ldc.i4 0
  10.     ldelem.ref
  11.     call       void [mscorlib]System.Console::WriteLine(string)
  13.     //return code
  14.     ldarg.0
  15.     ldlen
  16.     ret
  17. }


Line 7 is a comment. I believe you can use // at the end of any line, as I often see it in compiler-generated IL.

In line 8 we are loading the array onto the stack just as before.

In line 9 we see the “load a constant” command. The “.i4” suffix means that the constant is a 4-byte integer, a.k.a. a System.Int32. This is followed by the number 0, which we want. This gives us the following stack:


pointer to args

[not yours]

Line 10 starts with the “load element from array” command. It appears that the “.ref” suffix is used to indicate the array contains a non-numeric type. After this command is executed both the array and the constant will be removed from the stack and a pointer to the first string will be in its place. This is shown in the spec under the “stack transition” heading.



Version 3

Ok, now things get tricky. We are going to have to start keeping track of an array index. And since there are no loops in CIL, you have to fake it using if statements and gotos. Before we run off and start coding, lets write some pseudo code showing what we are trying to accomplish.

  1. Variables: index, arrayLength
  2. arrayLength = args.Length
  3. index = 0
  4. If index = arrayLength Then goto done
  5. Print args[index]
  6. index = index+1
  7. goto if
  8. done

Reminds me of BASICA back from the days of DOS, except you get labels instead of line numbers. Anyways, on to the code.

  1. .assembly extern mscorlib {}
  2. .assembly EchoProg {}
  3. .method static int32  Main(string[] args)
  4. {
  5.     .entrypoint
  6.     //Variables: index, arrayLength    
  7.     .locals init (
  8.         [0] int32 index,
  9.         [1] int32 arrayLength)
  11.     //arrayLength = args.Length
  12.     ldarg.0
  13.     ldlen
  14.     stloc 1
  16.     //index = 0
  17.     ldc.i4 0
  18.     stloc 0
  20.     //If index = arrayLength Then goto done
  21. if: ldloc 0
  22.     ldloc 1
  23.     beq done
  25.     //Print args[index]
  26.     ldarg.0
  27.     ldloc 0
  28.     ldelem.ref
  29.     call       void [mscorlib]System.Console::WriteLine(string)
  31.     //index = index+1
  32.     ldloc 0
  33.     ldc.i4 1
  34.     add.ovf
  35.     stloc 0
  37.     br if
  39. done:
  41.     //return code
  42.     ldarg.0
  43.     ldlen
  44.     ret
  45. }

On line 6 thru 9 we see our variables being defined. It starts with the “.locals” directive. This is followed by “init”, which sets all the local variables to 0/null. According to the spec, all verifiable code must use the init keyword.

Each well formed local variable consists of three values. First is the slot index, next is the variable type, and finally there is the variable name. Of these only the type is actually required. You could write, “.locals init (int32, int32)”, but that is going to be a royal pain to understand later on.

Lines 11 thru 14 load the array length into a local variable. The only thing new here is the “store local” command, which takes a slot number as a parameter.

Lines 16 thru 18 load the value 0 into the index variable. Strictly speaking this isn’t necessary because we are using init, but I’ll leave it here for reference.

Lines 20 to 23 represent our if statement. It starts with the label “if:” so we can jump to it later. We could have used just about anything for our label, it doesn’t really matter once the code is assembled.

Then we use the “load local” command twice, once for each variable.

Finally we use the “branch if equal” command on line 23. If the top-two items on the stack are equal, we go to line labeled “done”.

Lines 25 thru 29 is our code to actually print the parameter. The only difference between this and the one in version 2 is that we are loading the index using ldloc instead of a constant value.

Lines 31 to 35 will increment our index variable. It does this by loading both the index and the constant 1 onto the stack. Then it calls the “add with overflow check” command. Finally it stores the result value back into the index variable.

Line 37 takes us back to the top of the loop using the “branch” command. It is important that this line is skipped if our if statement back on line 20 is true.


I was surprised how much code it took to write this. Sure I knew I would have to write my own loops, but even basic stuff like incrementing local variables took much harder than I expected. I was expecting to find a “increment local” command, but it looks like we can’t do anything with values until they are on the stack.


Learning IL – Hello World in CIL

Filed under: CIL — Grauenwolf @ 6:38 am

If you are going to be writing your own programming language you need to spend a lot of time learning the target. In my case, the target is .NET’s Common Intermediate Language, also known as IL or CIL.  As per tradition, here is my hello world app written in CIL.

  1. .assembly extern mscorlib {}
  2. .assembly Test1 {}
  3. .method static void Main()
  4. {
  5.     .entrypoint
  6.     ldstr      “Hello World”
  7.     call       void [mscorlib]System.Console::WriteLine(string)
  8.     ret
  9. }

Line 1 says that I need mscorlib, but I don’t care which version. If it was important, then I would include some extra information in the brackets.

Line 2 is the name of my assembly.  I think I’m supposed to put assembly-level attributes in the brackets, but I’m not certain.

Line 3 starts my first function, or in IL parlance a “.method”. I bet you were expecting to see some sort of class or module, I sure as heck was. But no, that is not required.  The ECMA documentation clearly says, “Methods can be defined at the global level (outside of any type)”.  Well now, if that’s the case why not just go ahead and try it out.

Warning: Languages like VB and C# cannot call free-floating functions.

Ok, so what else do we know about line 3. Well it is an entry point function, so either it returns an integer or nothing. I choose nothing hence the “void” keyword. As for “static”, it seems kinda silly. Turns out the assembler will infer that it is a static method form the context, but since we don’t want warnings we will go ahead and put that in there.

Line 5 says that this is the entry point for the executable. For executables you must have one and only one entry point, the assembler won’t even try to sort it out if you break that rule.

Line 6 is translated as “load a string and push it onto the stack”. What follows is a QSTRING. From the spec:

QSTRING is a string surrounded by double quote (″) marks. Within the quoted string the character “\” can be
used as an escape character, with “\t” representing a tab character, “\n” representing a newline character, and
“\” followed by three octal digits representing a byte with that value. The “+” operator can be used to
concatenate string literals. This way, a long string can be broken across multiple lines by using “+” and a new
string on each line. An alternative is to use “\” as the last character in a line, in which case, that character and
the line break following it are not entered into the generated string. Any white space characters (space, line-
feed, carriage-return, and tab) between the “\” and the first non-white space character on the next line are
ignored. [Note: To include a double quote character in a QSTRING, use an octal escape sequence. end note]

You don’t have to use a QSTRING. You could instead use a SQSTRING. I don’t know why you would though, because literally the only difference is that it is wrapped in single quotes instead of double quotes.

Line 7 is a method call. (Not a function call; this is CIL and everything is a method.) Note that we have to be very explicit about what assembly the method lives in, what type wraps it, and which overload we desire.

Lets take a moment to talk about the stack. When you want to call a method you need to push the arguments onto the stack. When the method returns, if it has a non-void return type, the result will be pushed onto the stack. This means at run time your stacks are going to look something like this:

Before calling WriteLine After calling WriteLine
Pointer to “Hello World”  
[not yours] [not yours]

If you stray into the “not yours” part of the stack, say by calling WriteLine twice in a row, then bad things will happen. The assembler doesn’t care about double-checking the stack, so that won’t save you. There is a program called PEVerify that will warn you about potential stack underflows. If you don’t use it, then you find your error when your program crashes hard with an InvalidProgramException.

Line 8 is the return statement. If the function has a return value, it is copied from the top of the current stack to the top of the calling function’s stack. Since we aren’t returning anything, the stacks are not affected.

Blog at WordPress.com.