June 23, 2018

The Kyu shell or console

Once you have configured your board to run Kyu, you will be greated with something like the following and be wondering what the possibilities are. 
Kyu version 0.7.6 for orange_pi, Compiled by tom: Sat Jun 23 11:09:53 MST 2018 running
Kyu, ready>

Type "h" for help

This may serve to jog your memory if you forget all that is written here.

The "l" command

One of the handiest things to do is to type "l" and get a list of running threads: 
  Thread:       name (  &tp   )    state     esp     pri
  Thread:        net (40097358)     SEM J 404dc000   10
  Thread:   net_slow (4009726c)  REPEAT C 404dd000   11
  Thread:  xinu_time (40097530)     SEM J 404da000   28
  Thread:  xinu_tcpo (40097444)     SEM J 404db000   29
* Thread:      shell (40097708)   READY I 404d8000   30
  Thread:  xinu_test (40097180)     SEM I 404de000   30
  Thread:       idle (4009761c)   READY C 404d9000 1234
  Thread  Cur : (40097708)
The currently running thread will always be "shell", since that is the thread that runs the console interaction you are using. Note that this has an asterisk next to it. Also the last line gives the address of the current thread structure, which is redundant and matches the value of "&tp" for the thread thus flagged.

The thread name is whatever was given when the thread was created, chopped to the first 8 characters. The last two columns give the location of the stack and the priority for each thread.

The state field shows the thread state. Any state other than "READY" indicates that the thread is blocked for some reasons. The most common reason is "SEM" indicating the thread is blocked on a semaphore. The state "REPEAT" indicates that the thread is periodic and waiting on a time event.

The single letter (J, C, or I) above indicates the sort of resumption that will be used when the state becomes ready and begins execution. This is usually not of interest to the general public, but "J" indicates a synchronous resumption via a "jump" to swap registers. "I" indicates that an interrupt context was saved, and "C" indicates a continuation. These may be described elsewhere in developer documents, but hopefully this will satisfy the curious.

"d" to dump memory

You get several (four) flavors: So you can dump longs (32 bits), words (16 bits) or bytes. The count is the number of items (longs, words, or bytes) which is a scheme you may or may not find convenient.

The "di" command is a bypass that you may or may not find convenient. The "dl", "dw", and "db" commands all check the address range to see if it is valid (i.e. within a range it think corresponds to ram). The intent of this is to avoid the inconvenience of getting address aborts while poking around in memory. If you think you know what you are doing and want to bypass this safety chec, you can use the "di" command.

"R" to reboot

Typing "R" will cause a reset (or something morally equivalent) and reboot the board. This is infinitely useful while testing and developing code.

"x" to invoke C functions by name

The "x" command provides a limited ability to call C routines from the shell. This can be very handy and can be used to avoid writing tedious test parsers. It will only work in a decent way if you provide Kyu with a symbol table (as you should).

As the simplest case, typing "x thr_show" will call the C routine "thr_show" and produce the same output as the "l" command above. This works just fine for any C routine without arguments (i.e. with a "void" argument list).

The "x" command actually will handle a single argument. If none is given, it actually calls the function with an integer 0 (which is harmless for void functions). If an integer value is given, the function is called with that value, so "x my_test 13" will make the call my_test(13). If an argument has any non decimal digits, it is interpreted as a string and a pointer to the string is passed to the function. In other works "x my_test2 item4" will yield the call my_test2("item4"). If you have more than one argument, or want to call a function that expects a pointer to a structure or some such, you are out of luck.

Special test menus

At this time there are three of these, invoked by n, i, or k. This description will not discuss each and every test in these menus. Typing just the menu letter (i.e. "n" or "k" or whatever) will give a list of tests in that submenu, which are more or less explanatory. In most cases you will need to look at the source code to know what each test does.

Use the menu to get the number of the test and type "n 11" to run network test 11 for example. A handful of tests can be run multiple times via "n 17 100" (which would rerun test 17, 100 times). Most tests in the "n" and "i" menus ignore this repeat count. Those that allow it are designated by "[n]" in the description.

The "i" submenu is a grab bag of tests, many of which are hardware specific.

The "k" submenu is a set of regression tests for Kyu. Typing "k 0" will run all of the tests, which should always work. If it does not, email me or my twin brother and let us know. Typing "k 0 N" will repeat all of the tests N times. This has been useful in the distant past for uncovering race conditions which are only triggered by low probability timing issues.

Have any comments? Questions? Drop me a line!

Kyu / [email protected]