propeller-load -q what is "status"?

DavidZemon

I just found the propeller-load manual - very helpful! - and in it I found the "-q" flag. I'd like to use it for PropWare's unit tests, but don't know what "status" means when it says the exit sequence is

0xff 0x00 status

Is the status just my own byte for whatever I want, that will get displayed right before it exits? Or does it need to be a specific byte that signifies failure/success/whatever?

ersmith

SwimDude0614 wrote: »

I just found the propeller-load manual - very helpful! - and in it I found the "-q" flag. I'd like to use it for PropWare's unit tests, but don't know what "status" means when it says the exit sequence is

0xff 0x00 status

Is the status just my own byte for whatever I want, that will get displayed right before it exits? Or does it need to be a specific byte that signifies failure/success/whatever?

Status is typically the thing passed to the exit() function on the Propeller side. The meaning and interpretation is entirely up to you, although the usual convention in Unix systems is that 0 is success and non-zero values are failures. Also note that propeller-load doesn't print the status -- it calls exit() with that value, which shell scripts can detect and use.

The propeller libraries have a function __serial_exit that will override the normal exit routines so that exit(n) on the Propeller side will cause 0xff 0x00 n to be sent on the serial line to propeller-load, which will in turn cause it to exit with that value. To force the program to link with __serial_exit pass "-u __serial_exit" on the command line.

For example, here's part of lib/Test/Makefile, which is used to test library functions:

MODEL = xmmc
CC = propeller-elf-gcc
CFLAGS = -m$(MODEL) -std=c99 -Os -Wall -u __serial_exit

tests: time.run strtod.run scanf.run sprintf.run strtol.run wstring.run ctype.run

# [ various rules to build .elf file snipped here; they're very similar to the one below ]

mutex.elf: mutex.c $(LIBPTHREAD)
        $(CC) $(CFLAGS) -o $@ $^

%.run: %.elf
        propeller-load -bc3 $^ -r -t -q

Now if I do something like "make mutex.run" on the PC side, it will build mutex.elf and launch it with propeller-load -q. The combination of -u __serial_exit in the CFLAGS and -q in propeller-load means that propeller-load will exit with 0 (which make interprets as success) if and only if mutex.elf does so, In mutex.c there are various tests for mutexes; if any of them fail the program calls exit(1) (or abort(), or something similar that causes an abnormal exit).

Does that make any sense?

(The reason -u __serial_exit is required, instead of always having exit() on the propeller print the 0xff 0x00 n sequence, has to do with hardware faults in the Quickstart board, IIRC.)

SRLM

The `-q` flag is probably my favorite feature of propeller-load. It's what allows me to use unit tests on the Propeller, but have the results properly handled (without string parsing) on the computer side.

Here's where, as the status byte, I pass the number of failed tests. This conveniently maps to 0 == no error, and >1 == error.

https://github.com/libpropeller/libpropeller/blob/master/libpropeller/unity_tools/unity.cpp#L1162

Then in the test runner I take the propeller-load return value and pass that to Python's `sys.exit()` function:

https://github.com/libpropeller/libpropeller/blob/master/libpropeller/unity_tools/run_unit

All in all, it's a neat way to close the serial connection from the Propeller side.

DavidZemon

This is the most beautiful thing I've seen all week!!! Thanks!