__driver Struct Reference

Generic and customizable driver struct for stdio devices. More...

#include <propgcc/propeller-elf/include/sys/driver.h>

Collaboration diagram for __driver:

Public Attributes
const char *	prefix
int(*	fopen )(FILE *fp, const char *name, const char *mode)
int(*	fclose )(FILE *fp)
int(*	read )(FILE *fp, unsigned char *buf, int size)
int(*	write )(FILE *fp, unsigned char *buf, int size)
int(*	seek )(FILE *fp, long offset, int whence)
int(*	remove )(const char *name)
int(*	getbyte )(FILE *fp)
int(*	putbyte )(int c, FILE *fp)

Detailed Description

Generic and customizable driver struct for stdio devices.

The purpose is to allow replacing the stdio functions. Any device can be attached to stdio functions with this struct.

Typically the __driver array is defined by users for setting up stdin, stdout, stderr FILE drivers, SD card FILE drivers, and others.

The _Driver list is a list of all drivers we can use in the program. The default _InitIO function opens stdin, stdout, and stderr based on the first driver in the list (typically the serial driver). The serial driver could be replaced by a TV/Keyboard driver.

When defined by the user, the array of structs may look like this:

extern _Driver _SimpleSerialDriver;
extern _Driver _FileDriver;

_Driver *_driverlist[] = {
  &_SimpleSerialDriver,
  &_FileDriver,
  NULL
};

The NULL driver ends the _Driver list.

The device driver interface is the __driver struct. By defining the struct in the device driver, one connects driver functions to the _Driver.

In a TV output device driver for example, we need to define fopen() for the _InitIO() routine, fwrite(), and fclose().

_Driver TvDriver = {
  TvPrefix,     // TvPrefix is the device driver name "TV"
  Tv_fopen,     // fopen starts the TV COG (term for Propeller core).
  Tv_fclose,    // fclose stops the TV COG if necessary, etc....
  _null_read,   // use _null_read instead of defining Tv_fread
  Tv_write,     // fwrite is used to send characters to the TV
  NULL,         // seek; not applicable
  NULL,         // remove; not applicable
  NULL,         // getbyte; not applicable
  Tv_putbyte,   // putbyte: write a single byte
};

Of course it is not necessary to use a stdio method for TV output. There are some cases where the stdio infrastructure is not necessary. The standard stdio library is relatively big, but as small as possible.

The __driver mechanism gives the program flexibility in a standard way. The types of drivers are limited only by the programmer's imagination.

Some VGA demo programs have been written entirely in C.

Definition at line 88 of file driver.h.

Member Data Documentation

fclose

int(* __driver::fclose) (FILE *fp)

Prototype for closing files to be filled in by user's driver.

Parameters

[in,out]

fp

FILE pointer set by previous fopen() call.

Returns

0 on success, nonzero on failure

Definition at line 117 of file driver.h.

fopen

int(* __driver::fopen) (FILE *fp, const char *name, const char *mode)

Prototype for opening files.

A function for the user's device must be provided by the user's driver.

Parameters

[out]	fp	This is the file pointer for the driver.
[in]	name	This is the device name string.
[in]	mode	This is the device open mode string.

Returns

0 on success, nonzero on failure

Definition at line 110 of file driver.h.

getbyte

int(* __driver::getbyte) (FILE *fp)

Optional prototype for single character input.

Function getbyte is needed for reading the generic terminal driver.

Parameters

[in]

fp

The file pointer.

Returns

character read by the function.

Definition at line 164 of file driver.h.

prefix

const char* __driver::prefix

The file "device" prefix for fopen.

This string allows users to name their devices an pass startup information to the driver if nessesary.

Some library device names: "SSER", "FDS", "TV", etc....

The default Propeller-GCC stdio console device name is "SSER".

Definition at line 100 of file driver.h.

putbyte

int(* __driver::putbyte) (int c, FILE *fp)

Optional prototype for single character output.

Function putbyte is needed for writing to the generic terminal driver.

Parameters

	c	The character to write.
[in]	fp	The file pointer.

Returns

character written by the function.

Definition at line 173 of file driver.h.

read

int(* __driver::read) (FILE *fp, unsigned char *buf, int size)

Prototype for reading multi byte I/O.

A function for the user's device must be provided by the user's driver.

Parameters

[in,out]	fp	FILE pointer set by previous fopen() call.
[out]	buf	A char buffer of at least size length where data is put after read.
[in]	size	The size of the buf parameter.

Returns

The number of bytes read. If an error occurs, or the end-of-file is reached, the return value is a short object count (or zero).

Definition at line 128 of file driver.h.

remove

int(* __driver::remove) (const char *name)

Prototype for removing a file or directory from the file system.

Parameters

name	The name of the file to remove.

Returns

Zero on success, or -1 on error with errno set to indicate error.

Definition at line 156 of file driver.h.

seek

int(* __driver::seek) (FILE *fp, long offset, int whence)

Prototype for seek to a position in the file.

A function for the user's device must be provided by the user's driver.

Parameters

[in,out]	fp	FILE pointer set by previous fopen() call.
[in]	offset	The offset to add to the file position specified by whence.
[in]	whence	The start position specifier: SEEK_SET, SEEK_CUR, or SEEK_END.

Returns

Zero on success, or -1 on error with errno set to indicate error.

Definition at line 149 of file driver.h.

write

int(* __driver::write) (FILE *fp, unsigned char *buf, int size)

Prototype for writing multi byte I/O.

A function for the user's device must be provided by the user's driver.

Parameters

[in,out]	fp	FILE pointer set by previous fopen() call.
[in]	buf	A char buffer of at least size length where data is put befoe write.
	size	The size of the buf to write.

Returns

The number of bytes read. If an error occurs, or the end-of-file is reached, the return value is a short object count (or zero).

Definition at line 139 of file driver.h.

---

The documentation for this struct was generated from the following file:

• propgcc/propeller-elf/include/sys/driver.h