Skip to content

GaspardOS x64 system calls

Français

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.