#include <file.h>

int open (const char * path , unsigned flags , int file_descriptor );

The open function opens the file specified by path and prepares it for I/O.

• The path is the filename of the file to be opened, including an optional directory path and an optional device specifier (see Section 8.2.5).
• The flags are attributes that specify how the file is manipulated. The flags are specified using the following symbols:
O_RDONLY (0x0000) /* open for reading */ O_WRONLY (0x0001) /* open for writing */ O_RDWR (0x0002) /* open for read & write */ O_APPEND (0x0008) /* append on each write */ O_CREAT (0x0200) /* open with file create */ O_TRUNC (0x0400) /* open with truncation */ O_BINARY (0x8000) /* open in binary mode */

Low-level I/O routines allow or disallow some operations depending on the flags used when the file was opened. Some flags may not be meaningful for some devices, depending on how the device implements files.

• The file_descriptor is assigned by open to an opened file.

The next available file descriptor is assigned to each new file opened.

The function returns one of the following values:

#include <file.h>

int close (int file_descriptor );

The close function closes the file associated with file_descriptor.

The file_descriptor is the number assigned by open to an opened file.

The return value is one of the following:

#include <file.h>

int read (int file_descriptor , char * buffer , unsigned count );

The read function reads count characters into the buffer from the file associated with file_descriptor.

• The file_descriptor is the number assigned by open to an opened file.
• The buffer is where the read characters are placed.
• The count is the number of characters to read from the file.

The function returns one of the following values:

#include <file.h>

int write (int file_descriptor , const char * buffer , unsigned count );

The write function writes the number of characters specified by count from the buffer to the file associated with file_descriptor.

• The file_descriptor is the number assigned by open to an opened file.
• The buffer is where the characters to be written are located.
• The count is the number of characters to write to the file.

The function returns one of the following values:

#include <file.h>

off_t lseek (int file_descriptor , off_t offset , int origin );

The lseek function sets the file position indicator for the given file to a location relative to the specified origin. The file position indicator measures the position in characters from the beginning of the file.

• The file_descriptor is the number assigned by open to an opened file.
• The offset indicates the relative offset from the origin in characters.
• The origin is used to indicate which of the base locations the offset is measured from. The origin must be one of the following macros:

SEEK_SET (0x0000) Beginning of file

SEEK_CUR (0x0001) Current value of the file position indicator

SEEK_END (0x0002) End of file

The return value is one of the following:

#include <file.h>

int unlink (const char * path );

The unlink function deletes the file specified by path. Depending on the device, a deleted file may still remain until all file descriptors which have been opened for that file have been closed. See Section 8.2.3.

The path is the filename of the file, including path information and optional device prefix. (See Section 8.2.5.)

The function returns one of the following values:

#include {<stdio.h> | <file.h>}

int rename (const char * old_name , const char * new_name );

#include {<cstdio> | <file.h>}

int std::rename (const char * old_name , const char * new_name );

The rename function changes the name of a file.

• The old_name is the current name of the file.
• The new_name is the new name for the file.

NOTE

The optional device specified in the new name must match the device of the old name. If they do not match, a file copy would be required to perform the rename, and rename is not capable of this action.

The function returns one of the following values:

int DEV_open (const char * path , unsigned flags , int llv_fd );

This function finds a file matching path and opens it for I/O as requested by flags.

• The path is the filename of the file to be opened. If the name of a file passed to open has a device prefix, the device prefix will be stripped by open, so DEV_open will not see it. (See Section 8.2.5 for details on the device prefix.)
• The flags are attributes that specify how the file is manipulated. The flags are specified using the following symbols:
O_RDONLY (0x0000) /* open for reading */ O_WRONLY (0x0001) /* open for writing */ O_RDWR (0x0002) /* open for read & write */ O_APPEND (0x0008) /* append on each write */ O_CREAT (0x0200) /* open with file create */ O_TRUNC (0x0400) /* open with truncation */ O_BINARY (0x8000) /* open in binary mode */

See POSIX for further explanation of the flags.

• The llv_fd is treated as a suggested low-level file descriptor. This is a historical artifact; newly-defined device drivers should ignore this argument. This differs from the low-level I/O open function.

This function must arrange for information to be saved for each file descriptor, typically including a file position indicator and any significant flags. For the HOST version, all the bookkeeping is handled by the debugger running on the host machine. If the device uses an internal buffer, the buffer can be created when a file is opened, or the buffer can be created during a read or write.

This function must return -1 to indicate an error if for some reason the file could not be opened; such as the file does not exist, could not be created, or there are too many files open. The value of errno may optionally be set to indicate the exact error (the HOST device does not set errno). Some devices might have special failure conditions; for instance, if a device is read-only, a file cannot be opened O_WRONLY.

On success, this function must return a non-negative file descriptor unique among all open files handled by the specific device. The file descriptor need not be unique across devices. The device file descriptor is used only by low-level functions when calling the device-driver-level functions. The low-level function open allocates its own unique file descriptor for the high-level functions to call the low-level functions. Code that uses only high-level I/O functions need not be aware of these file descriptors.

int DEV_close (int dev_fd );

This function closes a valid open file descriptor.

On some devices, DEV_close may need to be responsible for checking if this is the last file descriptor pointing to a file that was unlinked. If so, it is responsible for ensuring that the file is actually removed from the device and the resources reclaimed, if appropriate.

This function should return -1 to indicate an error if the file descriptor is invalid in some way, such as being out of range or already closed, but this is not required. The user should not call close() with an invalid file descriptor.

int DEV_read (int dev_fd , char * buf , unsigned count );

The read function reads count bytes from the input file associated with dev_fd.

• The dev_fd is the number assigned by open to an opened file.
• The buf is where the read characters are placed.
• The count is the number of characters to read from the file.

This function must return -1 to indicate an error if for some reason no bytes could be read from the file. This could be because of an attempt to read from a O_WRONLY file, or for device-specific reasons.

If count is 0, no bytes are read and this function returns 0.

This function returns the number of bytes read, from 0 to count. 0 indicates that EOF was reached before any bytes were read. It is not an error to read less than count bytes; this is common if the are not enough bytes left in the file or the request was larger than an internal device buffer size.

int DEV_write (int dev_fd , const char * buf , unsigned count );

This function writes count bytes to the output file.

• The dev_fd is the number assigned by open to an opened file.
• The buffer is where the write characters are placed.
• The count is the number of characters to write to the file.

This function must return -1 to indicate an error if for some reason no bytes could be written to the file. This could be because of an attempt to read from a O_RDONLY file, or for device-specific reasons.

off_t lseek (int dev_fd , off_t offset , int origin );

This function sets the file's position indicator for this file descriptor as lseek.

If lseek is supported, it should not allow a seek to before the beginning of the file, but it should support seeking past the end of the file. Such seeks do not change the size of the file, but if it is followed by a write, the file size will increase.

If successful, this function returns the new value of the file position indicator.

This function must return -1 to indicate an error if for some reason no bytes could be written to the file. For many devices, the lseek operation is nonsensical (e.g. a computer monitor).

int DEV_unlink (const char * path );

Remove the association of the pathname with the file. This means that the file may no longer be opened using this name, but the file may not actually be immediately removed.

Depending on the device, the file may be immediately removed, but for a device which allows open file descriptors to point to unlinked files, the file will not actually be deleted until the last file descriptor is closed. See Section 8.2.3.

This function must return -1 to indicate an error if for some reason the file could not be unlinked (delayed removal does not count as a failure to unlink.)

If successful, this function returns 0.

int DEV_rename (const char * old_name , const char * new_name );

This function changes the name associated with the file.

• The old_name is the current name of the file.
• The new_name is the new name for the file.

This function must return -1 to indicate an error if for some reason the file could not be renamed, such as the file doesn't exist, or the new name already exists.

If successful, this function returns 0.

#include <file.h>

int add_device(char * name,
     unsigned flags,
     int (*dopen)(const char *path, unsigned flags, int llv_fd),
     int (*dclose)( int dev_fd),
     int (*dread)(intdev_fd, char *buf, unsigned count),
     int (*dwrite)(intdev_fd, const char *buf, unsigned count),
     off_t (*dlseek)(int dev_fd, off_t ioffset, int origin),
     int (*dunlink)(const char *path),
     int (*drename)(const char *old_name, const char *new_name));

lowlev.c (in the lib/src subdirectory of the compiler installation)

The add_device function adds a device record to the device table allowing that device to be used for I/O from C. The first entry in the device table is predefined to be the HOST device on which the debugger is running. The function add_device() finds the first empty position in the device table and initializes the fields of the structure that represent a device.

To open a stream on a newly added device use fopen( ) with a string of the format devicename:filename as the first argument.

• The name is a character string denoting the device name. The name is limited to 8 characters.
• The flags are device characteristics. The flags are as follows:

_SSA Denotes that the device supports only one open stream at a time

_MSA Denotes that the device supports multiple open streams

More flags can be added by defining them in file.h.

• The dopen, dclose, dread, dwrite, dlseek, dunlink, and drename specifiers are function pointers to the functions in the device driver that are called by the low-level functions to perform I/O on the specified device. You must declare these functions with the interface specified in Section 8.2.2. The device driver for the HOST that the TMS320C28x debugger is run on are included in the C I/O library.

The function returns one of the following values:

Example 8-2 does the following:

• Adds the device mydevice to the device table
• Opens a file named test on that device and associates it with the FILE pointer fid
• Writes the string Hello, world into the file
• Closes the file