HAL GDB File I/O Routines

Description

In some configurations an eCos application can perform a number of file I/O and other operations on the host by interacting with gdb. For example the application can open a log file to the host and write very large amounts of debug data to that file over a period of time while consuming minimal target-side resources. However, the application will be completely blocked for the duration of the I/O operation with interrupts globally disabled. The functionality uses the gdb File I/O Remote Protocol Extension, described in the Remote Protocol appendix of the gdb documentation.

The gdb file I/O support is only available when the configuration option CYGFUN_HAL_GDB_FILEIO is enabled. In turn that option will have dependencies on other parts of the HAL, and the required functionality will not be available for all targets.

When debugging involves a hardware debug solution such as jtag or BDM, typically gdb will interact with a remote protocol server running inside or controlling the hardware debug unit. That server will implement the core parts of the remote protocol such as accessing memory, but typically there will be no way for the eCos application to get the server to send specific requests such as for file I/O. Instead a different approach is used. From inside the gdb session the command set hwdebug should be used. The next time the eCos application attempts a file I/O operation it will cause execution to halt at _gdb_hwdebug_breakpoint. Code inside gdb recognises that address, retrieves details of the I/O request from the target's memory, and then acts as if the request had come in a remote protocol message. The target resumes execution automatically once the I/O operation has been performed. If the hwdebug flag has not been set or if the application is running outside a gdb debug session then all file I/O operations will fail with error code HAL_GDB_FILEIO_ENOSYS.

The Functions

Full details of the functions, parameters, data structures and error codes can be found in the header file cyg/hal/hal_gdb_fileio.h. The I/O calls are loosely modelled after the equivalent POSIX calls. They return 0 or a positive number for success, a negative number to indicate an error. The specific error code is the absolute value of the return value, so for example hal_gdb_fileio_open will return -HAL_GDB_FILEIO_ENOENT when attempting to open a file that does not exist. Some example code can be found in the testcase gdb_fileio.c.

hal_gdb_fileio_open is used to open a file on the host file system. It should only be used on files, not on special devices such as serial port or Unix-domain sockets: the gdb file I/O functionality is limited and has no support for select, non-blocking I/O, ioctl-style control, and so on. Hence if the eCos application does attempt to open and read from a serial port that will cause gdb to block and both the application and the debug session will freeze. Valid flags include HAL_GDB_FILEIO_O_RDONLY, HAL_GDB_FILEIO_O_WRONLY, and HAL_GDB_FILEIO_O_CREAT. The mode argument is used only when creating a new file and is used to set the access rights, for example HAL_GDB_FILEIO_S_IURSR+HAL_GDB_FILEIO_S_IWUSR.

The return value of hal_gdb_fileio_open is an integer file descriptor. Note that this is distinct from the file descriptor returned by the eCos open call. The two types of file descriptor are not interchangeable. For example hal_gdb_fileio_read should only be used with a file descriptor returned from hal_gdb_fileio_open, not with the return value of open.

hal_gdb_fileio_read, hal_gdb_fileio_write, hal_gdb_fileio_lseek, hal_gdb_fileio_fstat and hal_gdb_fileio_isatty perform operations on a file opened with hal_gdb_fileio_open. hal_gdb_fileio_write can also be used with the predefined file descriptor HAL_GDB_FILEIO_STDOUT, corresponding to gdb's standard output. For hal_gdb_fileio_lseek valid whence parameters are HAL_GDB_FILEIO_SEEK_SET, HAL_GDB_FILEIO_SEEK_CUR and HAL_GDB_FILEIO_SEEK_END. Due to limitations within the protocol and the implementation hal_gdb_fileio_lseek cannot fully support files of 2GB or larger. In other words offsets are limited to 31 bits.

The hal_gdb_fileio_stat and hal_gdb_fileio_fstat functions should be called with a struct hal_gdb-fileio_stat buffer:

struct hal_gdb_fileio_stat
{
    cyg_uint32 st_dev;
    cyg_uint32 st_ino;
    cyg_uint32 st_mode;
    cyg_uint32 st_nlink;
    cyg_uint32 st_uid;
    cyg_uint32 st_gid;
    cyg_uint32 st_rdev;
    cyg_uint64 st_size;
    cyg_uint64 st_blksize;
    cyg_uint64 st_blocks;
    cyg_uint32 st_atime;
    cyg_uint32 st_mtime;
    cyg_uint32 st_ctime;
};
    

The first argument to hal_gdb_fileio_gettimeofday should be hal_gdb_fileio_timeval structure:

struct hal_gdb_fileio_timeval
{
    cyg_uint32 tv_sec;
    cyg_uint32 tv_usec;
};
    

The second argument to hal_gdb_fileio_gettimeofday is not currently used and application code should use a NULL pointer for this.

hal_gdb_fileio_system can be used to invoke an arbitrary command on the host. For obvious security reasons this functionality is disabled within gdb by default. It must be explicitly enabled within gdb using a set remote system-call-allowed command.

Diagnostics Support

When the eCos application is built stand-alone and will be debugged via a hardware debug solution such as jtag or BDM, some platforms will allow HAL diagnostics to be sent a destination gdb_hwdebug_fileio. This output will end up being written to the gdb console via hal_gdb_fileio_write. Hence the output will be discarded unless the application is running inside a gdb session and the set hwdebug command has been used.