Collaboration diagram for GDB system call API:

Classes

class  GdbFileStream
 GDB File stream class to provide access to host files whilst running under debugger. More...
 
struct  gdb_stat_t
 GDB uses a specific version of the stat structure, 64 bytes in size. More...
 
struct  gdb_timeval_t
 GDB uses a specific version of the timeval structure, 12 bytes in size (manual says 8, which is wrong) More...
 
struct  GdbSyscallInfo
 GDB Syscall request information. More...
 

Typedefs

using gdb_syscall_callback_t = void(*)(const GdbSyscallInfo &info)
 GDB Syscall completion callback function. More...
 

Enumerations

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
}
 Enumeration defining available commands. More...
 

Functions

int gdb_syscall (const GdbSyscallInfo &info)
 Stub function to perform a syscall. Implemented by GDB stub. More...
 
static int gdb_syscall_open (const char *filename, int flags, int mode, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Open a file on the host. More...
 
static int gdb_syscall_close (int fd, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Close a host file. More...
 
static int gdb_syscall_read (int fd, void *buffer, size_t bufSize, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Read data from a host file. More...
 
static int gdb_syscall_write (int fd, const void *buffer, size_t count, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Write data from a host file. More...
 
static int gdb_syscall_lseek (int fd, long offset, int whence, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Get/set current file pointer position in a host file. More...
 
static int gdb_syscall_rename (const char *oldpath, const char *newpath, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Rename a host file. More...
 
static int gdb_syscall_unlink (const char *pathname, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Unlink/remove/delete a host file. More...
 
static int gdb_syscall_stat (const char *pathname, gdb_stat_t *buf, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Obtain information about a host file given its name/path. More...
 
static int gdb_syscall_fstat (int fd, struct gdb_stat_t *buf, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Obtain information about a host file given its file handle. More...
 
static int gdb_syscall_gettimeofday (gdb_timeval_t *tv, void *tz, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Get current time of day from host, in UTC. More...
 
static int gdb_syscall_isatty (int fd, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Determine if the given file handle refers to a console/tty. More...
 
static int gdb_syscall_system (const char *command, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Invoke the 'system' command on the host. More...
 
static int gdb_console_read (void *buffer, size_t bufSize, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Read a line of text from the GDB console. More...
 
static int gdb_console_write (const void *buffer, size_t count, gdb_syscall_callback_t callback=nullptr, void *param=nullptr)
 Write text to the GDB console. More...
 

Detailed Description

Typedef Documentation

◆ gdb_syscall_callback_t

using gdb_syscall_callback_t = void (*)(const GdbSyscallInfo& info)

GDB Syscall completion callback function.

Parameters
infoReference to request information, containing result code and user-provided 'param'

Enumeration Type Documentation

◆ GdbSyscallCommand

Enumeration defining available commands.

Enumerator
eGDBSYS_open 
eGDBSYS_close 
eGDBSYS_read 
eGDBSYS_write 
eGDBSYS_lseek 
eGDBSYS_rename 
eGDBSYS_unlink 
eGDBSYS_stat 
eGDBSYS_fstat 
eGDBSYS_gettimeofday 
eGDBSYS_isatty 
eGDBSYS_system 

Function Documentation

◆ gdb_console_read()

static int gdb_console_read ( void *  buffer,
size_t  bufSize,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Read a line of text from the GDB console.

Parameters
buffer
bufSize
callback
param
Return values
int
Note
IMPORTANT: Reading console will not complete until user types return (or Ctrl+D, Ctrl+C). It must therefore be an asynchronous call or a watchdog reset will occur.

◆ gdb_console_write()

static int gdb_console_write ( const void *  buffer,
size_t  count,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Write text to the GDB console.

Parameters
buffer
count
callback
param
Return values
int

◆ gdb_syscall()

int gdb_syscall ( const GdbSyscallInfo info)

Stub function to perform a syscall. Implemented by GDB stub.

Parameters
infoCall request information
Return values
Errorcode, < 0 for error or >= 0 for success
Note
If info.callback is null then the function waits until the request has been completed, and returns the result of the syscall. If info.callback is not null, then this function returns 0 to indicate the request is in progress, or a negative error value to indicate the request could not be started.
A copy of the request information is made and a reference passed to the completion callback function if one is used. Note that this is not the original structure, so it does not have to be persisent, although any char* or other pointers MUST remain valid until the call is completed.

◆ gdb_syscall_close()

static int gdb_syscall_close ( int  fd,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Close a host file.

Parameters
fdFile handle
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/close.html

◆ gdb_syscall_fstat()

static int gdb_syscall_fstat ( int  fd,
struct gdb_stat_t buf,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Obtain information about a host file given its file handle.

Parameters
fd
buf
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/stat_002ffstat.html

◆ gdb_syscall_gettimeofday()

static int gdb_syscall_gettimeofday ( gdb_timeval_t tv,
void *  tz,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Get current time of day from host, in UTC.

Parameters
tv
tzNot used, must be null
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/gettimeofday.html

◆ gdb_syscall_isatty()

static int gdb_syscall_isatty ( int  fd,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Determine if the given file handle refers to a console/tty.

Parameters
fd
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/isatty.html

◆ gdb_syscall_lseek()

static int gdb_syscall_lseek ( int  fd,
long  offset,
int  whence,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Get/set current file pointer position in a host file.

Parameters
fdFile handle
offsetRelative to whence
whenceSEEK_SET, SEEK_CUR or SEEK_END
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/lseek.html

◆ gdb_syscall_open()

static int gdb_syscall_open ( const char *  filename,
int  flags,
int  mode,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Open a file on the host.

Parameters
filenameName of file to open, relative to current directory (typically the Sming application folder)
flagsA combination of O_* flags defined in fcntl.h (e.g. O_RDONLY, O_CREAT, etc)
modeSee sys/stat.h
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/open.html

◆ gdb_syscall_read()

static int gdb_syscall_read ( int  fd,
void *  buffer,
size_t  bufSize,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Read data from a host file.

Parameters
fdFile handle
buffer
bufSize
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/read.html

◆ gdb_syscall_rename()

static int gdb_syscall_rename ( const char *  oldpath,
const char *  newpath,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Rename a host file.

Parameters
oldpath
newpath
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/rename.html

◆ gdb_syscall_stat()

static int gdb_syscall_stat ( const char *  pathname,
gdb_stat_t buf,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Obtain information about a host file given its name/path.

Parameters
pathname
buf
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/stat_002ffstat.html

◆ gdb_syscall_system()

static int gdb_syscall_system ( const char *  command,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Invoke the 'system' command on the host.

Parameters
command
callback
param
Return values
int
Note
For security reasons this command must specifically be enabled using 'set remote system-call-allowed 1'
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/system.html

◆ gdb_syscall_unlink()

static int gdb_syscall_unlink ( const char *  pathname,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Unlink/remove/delete a host file.

Parameters
pathname
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/unlink.html

◆ gdb_syscall_write()

static int gdb_syscall_write ( int  fd,
const void *  buffer,
size_t  count,
gdb_syscall_callback_t  callback = nullptr,
void *  param = nullptr 
)
inlinestatic

Write data from a host file.

Parameters
fdFile handle
buffer
count
callback
param
Return values
int
See also
https://sourceware.org/gdb/current/onlinedocs/gdb/write.html