FPGC6/Documentation/docs/Software/BDOS/syscalls.md

Syscalls

Syscalls, short for system calls, are a fundamental concept in operating systems. They provide a way for user-level (userBDOS) programs to interact with the underlying operating system (BDOS). Syscalls act as an interface between the user space and the OS space, allowing programs to request services from BDOS. Examples of syscalls include filesystem operations or writing to console.

Syscalls are essential for performing low-level operations and accessing system resources that are not directly/easily accessible from user-level programs. They provide a standardized and controlled way for programs to interact with the operating system.

Implementation

Syscalls are implemented by using some hardcoded reserved memory in the BDOS memory map. The program starts by writing the ID to this address. Then, the program adds optional arguments to each following word/address (so one word per arg: might be good to use a pointer if it does not fit in one word). Afterwards, the program backs up its registers to the hw stack, pushes the program counter to the hw stack and jumps to address 4.

By jumping to address 4, the CPU will then jump to the syscall() function of BDOS, as this jump statement is added during compilation of BDOS by the assembler. Then, BDOS will handle the syscall by reading the reserved memory to obtain the ID and arguments. The output is then written to the same address. Note, during this, a different stack is used to not interfere with the BDOS or program's stack.

Afterwards, BDOS will return from the syscall() function, pop the program counter saved by the user program, and jumpt to this program counter with an offset to land right after the jump to address 4. Afterwards, the registers are restored and the userprogram continues normally. Then, it can read the return values of the syscall by reading from the reserved memory address.

Syscall table

ID	Name	arg1	arg2	arg3	Description	Implemented
1	hid_checkfifo	-	-	-	Check if there is data in the HID FIFO	☑
2	hid_readfifo	-	-	-	Read next input from the HID FIFO	☑
3	bdos_printc	char c	-	-	Print a character to the console	☑
4	bdos_print	char* c	-	-	Print a null-terminated string to the console	☑
5	fs_open	char* path	-	-	Open a file	☑
6	fs_close	word fp	-	-	Close a file	☑
7	fs_read	word fp	word len	word* data	Read data from a file	☑
8	fs_write	word fp	word len	word* data	Write data to a file	☑
9	fs_setcursor	word fp	word pos	-	Set the cursor position in a file	☑
10	fs_getcursor	word fp	-	-	Get the cursor position in a file	☑
11	fs_delete	char* path	-	-	Delete a file or directory	☑
12	fs_mkdir	char* path	-	-	Create a directory	☑
13	fs_mkfile	char* path	-	-	Create a file	☑
14	fs_stat	char* path	-	-	Get file or directory information	☑
15	fs_readdir	char* path	-	-	Read a directory (TODO: think what to return)	☐
16	fs_getcwd	-	-	-	Get the current working directory	☑
17	fs_syncflash	-	-	-	Sync filesystem changes to SPI Flash	☑
18-19	reserved	-	-	-	Reserved for future use
20	shell_argc	-	-	-	Get the number of command-line arguments	☑
21	shell_argv	-	-	-	Get the command-line arguments	☑