gdb_syscall.h

Go to the documentation of this file.

/****
 * Sming Framework Project - Open Source framework for high efficiency native ESP8266 development.
 * Created 2015 by Skurydin Alexey
 * http://github.com/SmingHub/Sming
 * All files of the Sming Core are provided under the LGPL v3 license.
 *
 * gdb_syscall.h - Support for GDB file I/O
 *
 * @author: 2019 - Mikee47 <mike@sillyhouse.net>
 *
 * An API is defined for communicating with GDB using the 'file-I/O protocol', but the name is misleading
 * as it can also perform functions not related to file (or console) I/O. The functions are generally
 * POSIX compatible so for further details consult the appropriate reference for your operating system.
 *
 * This is a synchronous protocol, so only one request may be in progress at a time.
 * While a request is in progress GDB will not respond to any notifications from the target - including debug output.
 *
 * All functions are implemented with an optional callback routine, which is essential when reading the
 * console as it can take a considerable time to execute.
 *
 * To use in your application, build with GDBSTUB_ENABLE_SYSCALL=1 and #include this header.
 *
 * @see https://sourceware.org/gdb/current/onlinedocs/gdb/File_002dI_002fO-Remote-Protocol-Extension.html
 *
 ****/
 
#pragma once
 
#include <stdint.h>
#include <unistd.h>
#include <sys/fcntl.h>
#include <sys/stat.h>
#include <sys/unistd.h>
#include <sys/time.h>
#include <stdio.h>
 
#pragma pack(push, 4)
 
// When compiling under Linux, these get #defined and mess things up
#undef st_atime
#undef st_mtime
#undef st_ctime
 
struct gdb_stat_t {
    uint32_t st_dev;     // device
    uint32_t st_ino;     // inode
    mode_t st_mode;      // protection
    uint32_t st_nlink;   // number of hard links
    uint32_t st_uid;     // user ID of owner
    uint32_t st_gid;     // group ID of owner
    uint32_t st_rdev;   // device type (if inode device)
    uint64_t st_size;   // total size, in bytes
    uint64_t st_blksize; // blocksize for filesystem I/O
    uint64_t st_blocks;  // number of blocks allocated
    time_t st_atime;     // time of last access
    time_t st_mtime;     // time of last modification
    time_t st_ctime;     // time of last change
};
 
struct gdb_timeval_t {
    time_t tv_sec;  // second
    uint64_t tv_usec; // microsecond
};
 
#pragma pack(pop)
 
/* GDB Syscall interface */
 
enum GdbSyscallCommand {
    eGDBSYS_open,
    eGDBSYS_close,
    eGDBSYS_read,
    eGDBSYS_write,
    eGDBSYS_lseek,
    eGDBSYS_rename,
    eGDBSYS_unlink,
    eGDBSYS_stat,
    eGDBSYS_fstat,
    eGDBSYS_gettimeofday,
    eGDBSYS_isatty,
    eGDBSYS_system,
};
 
struct GdbSyscallInfo;
 
using gdb_syscall_callback_t = void (*)(const GdbSyscallInfo& info);
 
struct GdbSyscallInfo {
    GdbSyscallCommand command;       
    gdb_syscall_callback_t callback; 
    void* param;                     
    int result;                      
    // Command parameters
    union {
        struct {
            const char* filename;
            int flags;
            int mode;
        } open;
        struct {
            int fd;
        } close;
        struct {
            int fd;
            void* buffer;
            size_t bufSize;
        } read;
        struct {
            int fd;
            const void* buffer;
            size_t count;
        } write;
        struct {
            int fd;
            long offset;
            int whence;
        } lseek;
        struct {
            const char* oldpath;
            const char* newpath;
        } rename;
        struct {
            const char* pathname;
        } unlink;
        struct {
            const char* pathname;
            gdb_stat_t* buf;
        } stat;
        struct {
            int fd;
            struct gdb_stat_t* buf;
        } fstat;
        struct {
            gdb_timeval_t* tv;
            void* tz;
        } gettimeofday;
        struct {
            int fd;
        } isatty;
        struct {
            const char* command;
        } system;
    };
};
 
int gdb_syscall(const GdbSyscallInfo& info);
 
static inline int gdb_syscall_open(const char* filename, int flags, int mode, gdb_syscall_callback_t callback = nullptr,
                                   void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_open, callback, param};
    info.open.filename = filename;
    info.open.flags = flags;
    info.open.mode = mode;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_close(int fd, gdb_syscall_callback_t callback = nullptr, void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_close, callback, param};
    info.close.fd = fd;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_read(int fd, void* buffer, size_t bufSize, gdb_syscall_callback_t callback = nullptr,
                                   void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_read, callback, param};
    info.read.fd = fd;
    info.read.buffer = buffer;
    info.read.bufSize = bufSize;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_write(int fd, const void* buffer, size_t count, gdb_syscall_callback_t callback = nullptr,
                                    void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_write, callback, param};
    info.write.fd = fd;
    info.write.buffer = buffer;
    info.write.count = count;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_lseek(int fd, long offset, int whence, gdb_syscall_callback_t callback = nullptr,
                                    void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_lseek, callback, param};
    info.lseek.fd = fd;
    info.lseek.offset = offset;
    info.lseek.whence = whence;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_rename(const char* oldpath, const char* newpath,
                                     gdb_syscall_callback_t callback = nullptr, void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_rename, callback, param};
    info.rename.oldpath = oldpath;
    info.rename.newpath = newpath;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_unlink(const char* pathname, gdb_syscall_callback_t callback = nullptr,
                                     void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_unlink, callback, param};
    info.unlink.pathname = pathname;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_stat(const char* pathname, gdb_stat_t* buf, gdb_syscall_callback_t callback = nullptr,
                                   void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_stat, callback, param};
    info.stat.pathname = pathname;
    info.stat.buf = buf;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_fstat(int fd, struct gdb_stat_t* buf, gdb_syscall_callback_t callback = nullptr,
                                    void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_fstat, callback, param};
    info.fstat.fd = fd;
    info.fstat.buf = buf;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_gettimeofday(gdb_timeval_t* tv, void* tz, gdb_syscall_callback_t callback = nullptr,
                                           void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_gettimeofday, callback, param};
    info.gettimeofday.tv = tv;
    info.gettimeofday.tz = tz;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_isatty(int fd, gdb_syscall_callback_t callback = nullptr, void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_isatty, callback, param};
    info.isatty.fd = fd;
    return gdb_syscall(info);
}
 
static inline int gdb_syscall_system(const char* command, gdb_syscall_callback_t callback = nullptr,
                                     void* param = nullptr)
{
    GdbSyscallInfo info = {eGDBSYS_system, callback, param};
    info.system.command = command;
    return gdb_syscall(info);
}
 
static inline int gdb_console_read(void* buffer, size_t bufSize, gdb_syscall_callback_t callback = nullptr,
                                   void* param = nullptr)
{
    return gdb_syscall_read(STDIN_FILENO, buffer, bufSize, callback, param);
}
 
static inline int gdb_console_write(const void* buffer, size_t count, gdb_syscall_callback_t callback = nullptr,
                                    void* param = nullptr)
{
    return gdb_syscall_write(STDOUT_FILENO, buffer, count, callback, param);
}