Serial
[Core]

Serial provides a way to send and receive data via the serial port. More...


Functions
int	Serial_SetActive (int state)
	Set the active state of the Serial subsystem.
int	Serial_GetActive ()
	Read the active state of the Serial subsystem.
int	Serial_Write (uchar *buffer, int count, int timeout)
	Write a block of data to the Serial port.
int	Serial_Read (uchar *buffer, int size, int timeout)
	Read data from the Serial port.
int	Serial_GetReadable (void)
	Returns the number of bytes in the queue waiting to be read.
int	Serial_SetChar (int character)
	Sends a character (in the range of 0 to 255) to the write queue.
int	Serial_SetBaud (int baud)
	Sets the serial baud rate.
int	Serial_SetBits (int bits)
	Sets the number of bits per character.
int	Serial_SetParity (int parity)
	Sets the parity.
int	Serial_SetStopBits (int stopBits)
	Sets the stop bits per character.
int	Serial_SetHardwareHandshake (int hardwareHandshake)
	Sets whether hardware handshaking is being used.
int	Serial_GetChar ()
	Returns a single character from the receive queue if available.
int	Serial_GetBaud ()
	Returns the current baud rate.
int	Serial_GetBits ()
	Returns the number of bits for each character.
int	Serial_GetParity ()
	Returns the current parity.
int	Serial_GetStopBits ()
	Returns the number of stop bits.
int	Serial_GetHardwareHandshake ()
	Returns whether hardware handshaking is being employed or not.
void	Serial_Flush ()
	Clear out the serial port.
void	Serial_ClearErrors ()
	Reset the error flags in the serial system.
bool	Serial_GetErrors (bool overrun, bool frame, bool *parity)
	Read whether there are any errors.
void	Serial_StartBreak ()
	Start the transimission of a break.
void	Serial_StopBreak ()
	Stop the transimission of a break.

Detailed Description

Serial provides a way to send and receive data via the serial port.

The subsystem is supplied with small input and output buffers (of 100 characters each) and at present the implementation is interrupt per character so it's not particularly fast.

Permits all of the common serial characteristics to be set including:

baud - the speed of the connection (110 - > 2M) in baud or raw bits per second. 9600 baud is the default setting.
bits - the size of each character (5 - 8). 8 bits is the default setting.
stopBits - the number of stop bits transmitted (1 or 2) 1 stop bit is the default setting.
parity - the parity policy (-1 is odd, 0 is none and 1 is even). Even is the default setting.
hardwareHandshake - whether hardware handshaking is used or not. HardwareHandshaking is off by default.

Todo:: Convert to DMA interface for higher performance.

Function Documentation

void Serial_ClearErrors ( void )

Reset the error flags in the serial system.

In the normal course of operation, the serial system may experience a variety of different error modes, including buffer overruns, framing and parity errors, and more. When in an error state, the serial system may behave differently than normal.

Serial_ClearErrors() resets the appropriate status bits to a state of normal operation. It will only reset the error states if there are currently any errors.

See also:: Serial_GetErrors

Example

  Serial_ClearErrors();
  // that's all there is to it.

Definition at line 427 of file serial.c.

void Serial_Flush ( void )

Clear out the serial port.

Ensures that there are no bytes in the incoming buffer.

Example

  Serial_SetActive(1);
  Serial_Flush( ); // after starting up, make sure there's no junk in there

Definition at line 401 of file serial.c.

int Serial_GetActive ( void )

Read the active state of the Serial subsystem.

Returns:: State - 1/non-zero (on) or 0 (off).

Definition at line 99 of file serial.c.

int Serial_GetBaud ( void )

Returns the current baud rate.

Returns:: baud

Definition at line 330 of file serial.c.

int Serial_GetBits ( void )

Returns the number of bits for each character.

Returns:: bits

Definition at line 343 of file serial.c.

int Serial_GetChar ( void )

Returns a single character from the receive queue if available.

This character is returned unsigned - i.e. having a value of 0 - 255. The return value is -1 if there is no character waiting.

Returns:: character from the queue or -1 if there is no character.

Definition at line 305 of file serial.c.

bool Serial_GetErrors	(	bool *	overrun,
		bool *	frame,
		bool *	parity
	)

Read whether there are any errors.

We can check for three kinds of errors in the serial system:

buffer overrun
framing error
parity error

Each parameter will be set with a true or a false given the current error state. If you don't care to check one of the parameters, just pass in 0.

Parameters:

	overrun	A bool that will be set with the overrun error state.
	frame	A bool that will be set with the frame error state.
	parity	A bool that will be set with the parity error state.

Returns:: True if there were any errors, false if there were no errors.

See also:: Serial_ClearErrors( )

Example

  bool over, fr, par;
  if( Serial_GetErrors( &over, &fr, &par ) )
  {
    // if we wanted, we could just clear them all right here with Serial_ClearErrors()
    // but here we'll check to see what kind of errors we got
    if(over)
    {
      // then we have an overrun error
    }
    if(fr)
    {
      // then we have a framing error
    }
    if(par)
    {
      // then we have a parity error
    }
  }
  else
  {
    // there were no errors
  }

Definition at line 476 of file serial.c.

int Serial_GetHardwareHandshake ( void )

Returns whether hardware handshaking is being employed or not.

Returns:: hardwareHandshake

Definition at line 382 of file serial.c.

int Serial_GetParity ( void )

Returns the current parity.

-1 means odd, 0 means none, 1 means even

Returns:: parity

Definition at line 356 of file serial.c.

int Serial_GetReadable ( void )

Returns the number of bytes in the queue waiting to be read.

Returns:: bytes in the receive queue.

Definition at line 174 of file serial.c.

int Serial_GetStopBits ( void )

Returns the number of stop bits.

Returns:: stopBits

Definition at line 369 of file serial.c.

int Serial_Read	(	uchar *	buffer,
		int	size,
		int	timeout
	)

Read data from the Serial port.

Will block for the time specified (in ms) if there are insufficient characters. Blocking can be avoided if Serial_GetReadable( ) is used to determine how many characters are available to read prior to calling this function.

Parameters:

	buffer	A pointer to the buffer to read into.
	size	An integer specifying the maximum number of bytes to read.
	timeout	Time in milliseconds to block waiting for the specified number of bytes. 0 means don't wait.

Returns:: number of bytes read (>=0) or error <0 .

Definition at line 148 of file serial.c.

int Serial_SetActive ( int state )

Set the active state of the Serial subsystem.

This is automatically set to true by any call to Serial_Write or Serial_Read.

Parameters:

state

An integer specifying the active state - 1 (on) or 0 (off).

Returns:: CONTROLLER_OK (=0) on success.

Definition at line 73 of file serial.c.

int Serial_SetBaud ( int baud )

Sets the serial baud rate.

Parameters:

baud

The desired baud rate.

Returns:: status.

Definition at line 209 of file serial.c.

int Serial_SetBits ( int bits )

Sets the number of bits per character.

5 - 8 are legal values. 8 is the default.

Parameters:

bits

bits per character

Returns:: status.

Definition at line 226 of file serial.c.

int Serial_SetChar ( int character )

Sends a character (in the range of 0 to 255) to the write queue.

Parameters:

character

The character to be sent. Must be 0 <= c < 256.

Returns:: status.

Definition at line 184 of file serial.c.

int Serial_SetHardwareHandshake ( int hardwareHandshake )

Sets whether hardware handshaking is being used.

Parameters:

hardwareHandshake

sets hardware handshaking on (1) or off (0)

Returns:: status.

Definition at line 288 of file serial.c.

int Serial_SetParity ( int parity )

Sets the parity.

-1 is odd, 0 is none, 1 is even. The default is none - 0.

Parameters:

parity

-1, 0 or 1.

Returns:: status.

Definition at line 247 of file serial.c.

int Serial_SetStopBits ( int stopBits )

Sets the stop bits per character.

1 or 2 are legal values. 1 is the default.

Parameters:

stopBits

stop bits per character

Returns:: status.

Definition at line 267 of file serial.c.

void Serial_StartBreak ( void )

Start the transimission of a break.

This has no effect if a break is already in progress.

Example

  Serial_StartBreak();

Definition at line 511 of file serial.c.

void Serial_StopBreak ( void )

Stop the transimission of a break.

This has no effect if there's not a break already in progress.

Example

  Serial_StopBreak();

Definition at line 526 of file serial.c.

int Serial_Write	(	uchar *	buffer,
		int	count,
		int	timeout
	)

Write a block of data to the Serial port.

Will block for the time specified (in ms) if the queue fills up.

Parameters:

	buffer	A pointer to the buffer to write from.
	count	An integer specifying the number of bytes to write.
	timeout	Time in milliseconds to block waiting for the queue to free up. 0 means don't wait.

Returns:: status.

Definition at line 112 of file serial.c.


	Make Controller Kit Firmware API

Serial [Core]

Functions

Detailed Description

Function Documentation

Serial
[Core]