GaspardOS x64 system calls¶
GaspardOS originally used custom system calls. Porting newlib brought its file and networking services closer to Unix interfaces, making C and C++ software easier to port. This does not imply full POSIX support or compatibility with the Linux system call ABI.
This page covers x86-64, the System V AMD64 ABI and the LP64 data model only:
pointers, long and size_t are 64 bits, and wchar_t is 32 bits.
The historical i686 interface and int 0x80 are outside its scope.
Choosing an interface¶
Use newlib for ordinary operations: fopen, open, read, write, stat,
getcwd or chdir. The C library adapts paths, flags and errors to kernel
services. Handwritten assembly is not required. The GO64_* C wrappers
expose the native interface, including windows, rendering and process
launching. The C++ and Fortran bindings also use these wrappers.
Native calling convention¶
The wrappers execute SYSCALL with the service number in RAX and up to
six arguments in RDI, RSI, RDX, R10, R8 and R9. RAX receives
the result. The instruction overwrites RCX and R11; the transport also
declares memory and condition-code effects.
Services that return a value use int64_t, with negative values indicating
native errors. GO64_exit does not return. Newlib translates errors to its
own errno values and each C function's return convention: test fopen
against NULL, open against -1, and so on. Native error numbers and
newlib's errno values must not be confused.
Pointers refer to the calling process's user memory. Preserve the structure
sizes and alignment specified in the x64 header. Do not use -fshort-wchar
or force structure packing.
x64 system call table¶
Site/refresh_sources.py collects numbers and signatures from the native
wrapper header. The table covers services exposed by this repository's
bindings, rather than private extensions of other components.
45 syscalls exposed by the repository x64 wrappers.
| Number | C wrapper |
|---|---|
| 0 | int64_t GO64_ticks(void) |
| 1 | int64_t GO64_console_write(const void* buffer, uint64_t size) |
| 2 | int64_t GO64_yield(void) |
| 3 | void GO64_exit(void) |
| 4 | int64_t GO64_alloc(uint64_t size) |
| 5 | int64_t GO64_free(void* pointer) |
| 100 | int64_t GO64_fs_open(const wchar_t* path, uint64_t flags) |
| 101 | int64_t GO64_fs_close(int64_t fd) |
| 102 | int64_t GO64_fs_read(int64_t fd, void* buffer, uint64_t size) |
| 103 | int64_t GO64_fs_write(int64_t fd, const void* buffer, uint64_t size) |
| 104 | int64_t GO64_fs_seek(int64_t fd, int64_t offset, uint64_t origin) |
| 105 | int64_t GO64_fs_stat(const wchar_t* path, GO64_FSInfo* info) |
| 106 | int64_t GO64_fs_fstat(int64_t fd, GO64_FSInfo* info) |
| 107 | int64_t GO64_fs_mkdir(const wchar_t* path) |
| 108 | int64_t GO64_fs_unlink(const wchar_t* path) |
| 109 | int64_t GO64_fs_rmdir(const wchar_t* path) |
| 110 | int64_t GO64_fs_truncate(int64_t fd, uint64_t size) |
| 111 | int64_t GO64_fs_readdir(int64_t fd, GO64_FSInfo* info) |
| 112 | int64_t GO64_fs_rename(const wchar_t* oldpath, const wchar_t* newpath) |
| 113 | int64_t GO64_fs_fcntl(int64_t fd, uint64_t command, uint64_t flags) |
| 120 | int64_t GO64_socket(uint64_t family, uint64_t type, uint64_t protocol) |
| 121 | int64_t GO64_bind(int64_t fd, const GO64_SocketAddress* address, uint64_t address_size) |
| 122 | int64_t GO64_listen(int64_t fd, int64_t backlog) |
| 123 | int64_t GO64_accept(int64_t fd, GO64_SocketAddress* address, uint32_t* address_size) |
| 124 | int64_t GO64_connect(int64_t fd, const GO64_SocketAddress* address, uint64_t address_size) |
| 125 | int64_t GO64_send(int64_t fd, const void* buffer, uint64_t size, uint64_t flags) |
| 126 | int64_t GO64_recv(int64_t fd, void* buffer, uint64_t size, uint64_t flags) |
| 127 | int64_t GO64_sendto(int64_t fd, const void* buffer, uint64_t size, uint64_t flags, const GO64_SocketAddress* address, uint64_t address_size) |
| 128 | int64_t GO64_recvfrom(int64_t fd, void* buffer, uint64_t size, uint64_t flags, GO64_SocketAddress* address, uint32_t* address_size) |
| 129 | int64_t GO64_getsockname(int64_t fd, GO64_SocketAddress* address, uint32_t* address_size) |
| 130 | int64_t GO64_getpeername(int64_t fd, GO64_SocketAddress* address, uint32_t* address_size) |
| 131 | int64_t GO64_socket_close(int64_t fd) |
| 132 | int64_t GO64_log(const char* text) |
| 140 | int64_t GO64_window_create(const GO64_WindowOptions* options) |
| 141 | int64_t GO64_window_destroy(uint64_t window) |
| 142 | int64_t GO64_window_fill(uint64_t window, const GO64_Drawing* drawing) |
| 143 | int64_t GO64_window_text(uint64_t window, const GO64_Drawing* drawing) |
| 144 | int64_t GO64_window_event(uint64_t window, GO64_Event* event, uint64_t mode) |
| 145 | int64_t GO64_window_focus(uint64_t window) |
| 146 | int64_t GO64_window_blit(uint64_t window, const GO64_Blit* tile) |
| 150 | int64_t GO64_process_spawn(const void* image, uint64_t size, uint64_t argc, const char* const* argv) |
| 151 | int64_t GO64_process_read(void* buffer, uint64_t size) |
| 152 | int64_t GO64_process_status(void) |
| 153 | int64_t GO64_process_getcwd(char* buffer, uint64_t size) |
| 154 | int64_t GO64_process_chdir(const char* path) |
Service groups¶
| Numbers | Services |
|---|---|
| 0–5 | Ticks, console output, yielding, termination and user memory. |
| 100–113 | Files and directories: open, read, write, seek, metadata, creation, removal and rename. |
| 120–131 | IPv4 TCP/UDP sockets. |
| 132 | Kernel logging. |
| 140–146 | Windows, events, drawing and pixel tile copies. |
| 150–152 | Launching an ELF64 child, reading its output and counting children not yet reaped. |
| 153–154 | Reading and changing the process's current directory. |
File and socket services may return -11 when the caller needs to yield
and retry. Windows are asynchronous: wait for GO64_READY before drawing.
process_spawn returns a task token, rather than the child's exit status.
Newlib and the current directory¶
The shared backend is compiled with GASPARDOS_NEWLIB_X64 to select the x64
transport. Its i686 compatibility branches do not change the ABI covered here.
| Newlib function | x64 service or adaptation |
|---|---|
fopen, open |
Resolve UTF-8 paths, convert to UTF-32, then call GO64_fs_open (100). |
read, write, close |
File services, with special handling for console descriptors. |
stat, mkdir, unlink, rmdir, rename |
Corresponding native file services. |
getcwd |
process_getcwd (153), adapted to the C contract, including getcwd(NULL, 0). |
chdir |
process_chdir (154), followed by a refresh of the C library's local state. |
| Relative opens | Read the kernel's current directory before constructing an absolute path. |
The kernel stores a directory for each process. Children inherit a copy:
their chdir does not change the parent's directory. With no parent,
the initial directory is /IDEDISK0/. The terminal's cd updates this
directory before launching a child. On older kernels returning -38 for
153 or 154, newlib retains its historical local directory handling.
Native file calls still require absolute UTF-32 paths. Calls 153 and 154
use UTF-8. process_getcwd returns the number of bytes copied, including
NUL; -34 means the buffer is too small. process_chdir accepts relative
paths, . and .., checks the directory and returns zero or a negative
error. Stored paths end with / and use at most 4095 bytes, excluding NUL.
After cd /AHCIDISK0/project in the terminal, a program linked with the
updated C library can open project files using relative paths:
#include <stdio.h>
#include <unistd.h>
int main(void)
{
char cwd[4096];
if (!getcwd(cwd, sizeof(cwd))) { perror("getcwd"); return 1; }
printf("cwd: %s\n", cwd);
FILE *file = fopen("Vars.com", "r"); /* or "Makefile" */
if (!file) { perror("Vars.com"); return 1; }
return fclose(file) == 0 ? 0 : 1;
}
Existing executables must be relinked with the updated library. GCC and binutils do not need to be rebuilt for this change.
Collected sources¶
The collection preserves complete files, including the shared backend's
i686 compatibility branches. This page concerns builds using
GASPARDOS_NEWLIB_X64.