VS1010 System Utility Programs Explained

[Panu]

Dear VS1010 users,

In this thread, I will document the small VSOS utilities that are distributed in VS1010 root images. They are small programs and libraries that you can call from your own programs or run from the command line.

To avoid cluttering this thread, please use this thread for any feedback or questions that you have about the standard utilities.

[Panu]

ECHO is a system utility, that takes a line of text as a parameter and writes it out to standard output. It's source code is here:

Code: Select all

#include <vo_stdio.h>

ioresult main (char *params) {
	printf("%s", params);
	return S_OK;
}

ECHO is a very simple program. It prints a line of text. For example, a command "ECHO Hello, World!" entered from the command line causes the text "Hello, World!" to show on the console. But how does it work, exactly?

All VSOS programs should begin with the line "#include <vo_stdio.h>". This reflects the standard C input and output library, stdio.h, which is traditionally the first line of legacy C programs. The difference between <stdio.h> and <vo_stdio.h> is subtle, but significant. Stdio.h uses the VLSI traditional VS3EMU debugger input/output, but vo_stdio.h uses VSOS standard input and output. Using stdio.h instead of vo_stdio.h in VSOS programs will probably result in errors (unless you know exactly what you are doing). Stdio.h allows you to open files in PC debugger (applicable only to kernel solutions). Vo_stdio.h enables VSOS console, screen and file input and output. Only one can be included in a single C file.

Following the ancient C paradigm, a function named "main" is the standard entry point of programs: normal execution of programs starts from the beginning of "main". It's not the only entry point however; just as VSOS in VS1005, also VS1010 programs have two other standard entry points: init() and fini(), which are discussed elsewhere. They work similarly as they work in VS1005.

The main() function takes one parameter: a single pointer to the string of arguments passed to the program, either from the command line or from another calling program. If they need to be splitted into a vector of individual strings, it can be done using an external utility.

Inside the main function, line "printf("%s", params);" is normal C code that prints out a string. It works just like it would work in any PC or home computer. It takes the command line argument string and passes it to the printf() function, which is included inside the VS1010 ROM, along with all the mechanisms that are needed to handle file input and output. The printf() function formats the string and sends it to a special file handle, stdout, "standard output". The VSOS operating system takes it from there, and prints the line of text to whatever device the current terminal might be. By default, it goes to the UART and to the internal CRT debug console.

Finally, the program returns S_OK, e.g. "no error", which is the integer value 0. For any caller program interested in the return value, it denotes that the command has completed successfully.

Below you can download the source code of ECHO. You can use VSIDE to compile the code into a VS1010 executable file HELLO.DLX ("DLX" stands for VSOS "Dynamically Loadable Executable"). That file can be placed into the SYS folder of your board's SD card, or to a flash memory, if your board is configured to use a flash memory as the System disk S:. If you've ever used VS1005, these mechanisms should be fairly familiar to you.

--
Questions? Ask here.

[Panu]

TYPE takes a file name as an argument and copies its contents line by line to stdout. The effect is that you can see the contents of the file on the console, which is a UART serial port by default.

Code: Select all

// VS1010 source code for the program "type"
#include <vo_stdio.h>

ioresult main (char *params) {
	FILE *f=fopen(params,"r");
	static char buf[300];
	if (f) {
		while(1) {
			fgets(buf,sizeof(buf)-1,f);
			if (feof(f)) break;
			printf(buf);
		}
		fclose(f);
		return S_OK;
	} else {
		printf(" File not found.");
	}

}

VSOS uses standard C file interface functions for handling files. Files are opened with fopen() and closed with fclose(). File names in VSOS need to be absolute, e.g. they must start with a drive letter and a colon. There is no concept of a "current directory". Forward slashes are used as directory delimiters. A directory name is denoted by a file name ending with a forward slash (e.g. "S:SYS/"). "S:SYS/TYPE.DLX" is a valid VSOS file name.

After opening the file, it is read, line by line to the static buffer buf and printed to stdout from there. It's usually not a good idea to allocate large buffers from the stack. There's 2K doublewords of stack space in the VS1010. It's more than there is in the VS1005, so allocating buffers from the stack is not such a strict no-no as it is in the VS1005, and sometimes it's a good idea. But if you do it too often, you will run out from stack space, so using static allocation for buffers is generally recommended. Statics and globals also use direct accessing and are relocated at load time, which generates faster and smaller code than using stack based variables and buffers.

[Panu]

Code: Select all

// VS1010 source code for the program "devices"
#include <vo_stdio.h>

ioresult main (char *params) {
	u_int16 i;
	for (i=0; i<('Z'-'A'+1); i++) {
		if (vo_pdevices[i]) {
			printf("%c: %s\n",'A'+i,Identify(vo_pdevices[i]));
		}
	}
	return S_OK;
}

In VSOS, a DEVICE is an object that has properties and methods for handling data in a standard way. And some devices can contain something that can be accessed as files and opened with fopen(). Data files in an SD card are an obvious example.

Earlier, in the documentation of TYPE, it was stated that fopen() needs an absolute path filename, that starts with a device letter and a colon. So how are those device letters defined?

Inside the kernel data area, there is an array of 26 pointers to DEVICEs. These are called "VSOS System Devices" and are those devices that have a corresponding device letter. The first pointer in the DEVICE *vo_pdevices[26] array corresponds with letter "A". The next with letter "B", third with the letter "C", fourth with the letter "D" and so on. So if you have a file name "D:MUSIC/SONG.MP3" and you pass that string as an argument to fopen, VSOS looks at the fourth pointer in the vo_pdevices array. What happens after that is intriguing but less than magical. You can look at the kernel sources, function vo_fopen, file vsos.c to find out more. Basically a file descriptor object is generated and populated with methods based on the device and filesystem descriptors that match with the drive letter.

DEVICES.DLX is a small utility that shows the names of devices that are currently assigned to device letters in the array. For each nonzero pointer, it calls Identify(), which should return a human readable name for any VSOS object, such as a DEVICE, FILE or FILESYSTEM. Based on this source code, you can experiment with the Identify() function. Just don't pass a random variable to it - unexpected errors may occur if the parameter is nonzero but does not point to a VSOS device.