boldinventions.com

KCMD Command Processor Documentation - Getting Started 4

<-- PREV PAGE

Introduction to the Stack

The KCMD command processor works like a RPN calculator. This means that if you type in a number, it simply goes on the stack. It stays there until a command of some kind takes it off to use it. In KCMD, the stack is a maximum of 8 elements deep by default. There is a command which can display the entire stack contents without changing it. This command is .stack.

In these examples we use the color blue to designate the characters the user is typing.

PROMPT> 1 2 3 .stack

1 2 3

PROMPT>

In this exciting exchange, we have placed three numbers on the stack, 1 2 and 3. Then we typed out the stack, and our three numbers were there.

Now we also have a command called '.' which removes the top number from the stack, and types it out for us. So right now we still have three numbers on the stack, so we just issue the '.' command by typing a period and hitting enter:

PROMPT> . 3

PROMPT> .stack

1 2

PROMPT>

We typed the period (it is blue but you can't really tell) and then the enter key, and kcmd typed the '3'. Now when we do '.stack' again, we see there now only two numbers on the stack.

The three is now gone. It was removed when we used the '.' command to type out the top of stack. Notice that the first item to get removed is the last number we put on the stack. The stack is a last-in first-out kind of storage.

KCMD Arithmetic

The command processor can do basic arithmetic like addition, subtraction, multiplication and division. Commands could easily be added for AND, OR and NOT and so on.

Assuming there are still two numbers on the stack, 1 and 2. If we use the '+' command, it removes two numbers from the top of the stack and adds them. It then puts the result back on the stack. So if we have 1 and 2 on the stack, then we execute the '+' command, we shall end up with just a 3 on the stack.

PROMPT> 1 2

PROMPT> .stack

1 2

PROMPT> +

PROMPT> .stack

3

PROMPT>

Have you ever used an RPN calculator? How about a more complicated expression, such as (((1+7)*3)-4)/2?

PROMPT> 1 7 + 3 * 4 - 2 /

PROMPT> . 10

PROMPT>

So a 1 and a 7 get put on the stack, then the '+' command replaces the 1 and 7 with 8. Then a 3 gets added to the stack, since that is the next word after the '+'. Now there is a 3 and an 8 on the stack. Then the '*' command takes the 3 and the 8 off the stack, multiplies them, and places a 24 on the stack. The next word is a 4, so then the stack has a 24 and 4 on it. The '-' command takes the 24 and the 4, and replaces them with a 20. The next command is a 2, so then the stack has a 20 and a 2 on it. The '/' command takes the 20 and the 2 off the stack, and puts a 10 on the stack.

On the next line, we type the '.' command to type out the top of stack, and the 10 is printed, and now the stack is empty.

Entering Hexidecimal Values

When entering numbers, if the number is preceded by '0x' it is considered a hexidecimal value.

PROMPT> 0x10 .stack

16

PROMPT>

So hexidecimal 0x10 is equal to decimal 16. You can mix and match decimal and hexidecimal as you please.

In addition, you can change the default numeric base for output so that all numbers are printed out in hexidecimal if preferred. To do this, put a 16 on the stack, then use the 'base' command.

PROMPT> 16 base

Number Base set to 16.

PROMPT> 9 10 11 12 13 14 15 16 .stack

9 a b c d e f 10

PROMPT> . 10

PROMPT> . f

PROMPT> . e

PROMPT> . d

PROMPT> . c

PROMPT> . b

PROMPT> . a

PROMPT> . 9

PROMPT> .

Stack Empty!

However, this is confusing, because changing the base only affects number output, not input. So we put 8 numbers on the stack in decimal, but now .stack prints them out in hexidecimal.

To restore the base to 10, just put a 10 on the top of the stack and use the base command.

PROMPT> 10 base

Number Base set to 10.

PROMPT>

Stack Manipulation

There are a bunch of commands which can duplicate or move numbers on the stack. The 'dup' command for example will make a copy of the top element on the stack and add it to the stack:

PROMPT> 5 7 1 .stack

5 7 1

PROMPT> dup

PROMPT> .stack

5 7 1 1

PROMPT>

The 'dup' command duplicated the '1' so the stack now has two 1s on it.

The 'swap' command does what you'd expect.

The 'over' command is a dup, but it duplicates the 2nd from the top instead of the top element.

Accessing Memory

KCMD can examine or change memory contents. It does this by interpreting the top element on the stack as a memory address. Then the '@' command will remove the number on the top of stack and replace it with the memory contents at that address. Unfortunately on the Windows platform, we can't just inspect any memory address, since much of the memory we don't the right to access.

KCCHAR KCCATTR g_str_hello_world[] = "\r\nhello, world. Ptr to this string: 0x%0x\r\n";

int main (int arcg, char *argv[])

{

int iExitFlag;

printf(g_str_hello_world, g_str_hello_world);

To get a pointer we can legally look at, lets make the hello world string be a constant character array and have the main() function type out the value of that pointer for us. Below we type in that memory address on the top of stack, and then type the contents out. At first the contents are in decimal which isn't very useful, so we switch the number output base to 16 to get the hexidecimal value.

hello, world. Ptr to this string: 0x419c0c

KCMD Command Processor

For cmd list type help

PROMPT> 0x419c0c @

PROMPT> .stack

1701317133

PROMPT> 16 base

Number Base set to 16.

PROMPT> .stack

65680a0d

PROMPT>

OK, 0x65680a0d is four characters. 0d = '\r' , 0a = '\n' 0x68 = 'h' and 0x65 = 'e'. These are the first four characters in the string 'hello, world'.

Typing out a Memory Dump

We have a command which can dump a region of memory. Takes the memory address and the count on the stack. Remember to type the memory address first, then the count.

msvc2008-bdump

Here we see the result. We have dumped 50 bytes starting at location 0x419c0c. This would be the 'hello, world' string. The address is on the left, the bytes are numerically represented in the middle, and the ascii equivalents are on the right. If a byte does not have an ascii printable character, a '.' is shown instead.

Conclusion

This concludes the Getting Started section. We've accomplished a lot. A project was started from scratch, the KCMD processor source was added to the project and configured, and we learn how to use most of the basic commands. In order to make KCMD really useful, you need to be able to make your own custom commands. This will be covered in the next section.

<-- PREV PAGE