Serial Communication Functions

Gets a weak ownership of the port. Subsequent calls to this function with the same parameter will fail unless SERIAL_Close() is called for the same port.

Synopsis

int SERIAL_Open( int port );

Parameter	Description
`port`	Serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.

Return Code

0: Port opened successfully

others: An error prevented the serial port from opening

Comments

This function in no way guarantees safe sharing of the ports.

Any application can call SERIAL_Close() to get the access to the port, or can use SERIAL functions without opening the port first.

SERIAL_Close

This function is used to release ownership of the serial port.

Synopsis

void SERIAL_Close(int port);

Parameter	Description
`port`	Serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.

Return Code

N/A

Comments

See SERIAL_Open

SERIAL_InitPort

This function initializes the specified serial port to the parameters “9600 8N1” with no handshake.

Synopsis

int SERIAL_InitPort(int port);

Parameter	Description
`port`	Serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.

Return Code

0: The serial port was initialized successfully.

-1: There was an error initializing the port.

SERIAL_SendData

SERIAL_SendData() function is used to send a character array over a serial port.

Synopsis

#include <serial.h>  applies to all SERIAL_* functions
int SERIAL_SendData(int port, 
unsigned char *buf, 
int bufLen, 
long timeout);

Parameter	Description
`port`	Serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.
`buf`	Pointer to an array of bytes to be sent
`bufLen`	Length of the buffer, in bytes
`timeout`	Milliseconds to wait for a character to be sent. A timeout of -1 will use the default timeout. NOTE The timeout value refers to the total time taken to send the data. For example, a 2 millisecond timeout for sending 10 characters in 9600 baud setting will always fail - the timeout must be at least 10 milliseconds.

Return Code

0: The characters were sent successfully.

-1: There was an error.

SERIAL_WaitReply

The SERIAL_WaitReply() function waits for a character to appear on the serial port.

Synopsis

int SERIAL_WaitReply( int port );

Parameter	Description
`port`	serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.

Return Code

0: There is a character at the serial port.

-1: Timeout occurred, and no data appeared.

SERIAL_ReceiveData

The SERIAL_ReceiveData() function is used to receive an arbitrary length of characters from the serial port.

Synopsis

int SERIAL_ReceiveData(int port, 
unsigned char *buf, 
int *len, 
int bufLen,
long timeout);

Parameter	Description
`port`	Serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.
`buf`	Pointer to an array of bytes, which will hold the received data.
`len`	Pointer to an integer which will hold the actual number of characters received.
`bufLen`	Both the maximum amount of data, in bytes, of the buffer,and the number of bytes requested from the serial port.
`timeout`	Milliseconds to wait for a character to appear. A timeout of -1 will use the default timeout

Return Code

0: Requested number of bytes has been received.

-1: Less than the requested number of bytes have been received.

SERIAL_FlushRX

This function flushes the receive buffer of the specified serial port.

Synopsis

void SERIAL_FlushRX( int port );

Parameter	Description
`port`	Serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.

SERIAL_GetControlLines

This function reads the current state of the control lines, and writes a bitmap into the address pointed to by 'val'. Only the input bits (CTS, DSR, DCD, RI) reflect the current status of control lines.

Synopsis

int SERIAL_GetControlLines( int port, 
unsigned char *bitmap);

Parameter	Description
`port`	Serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.
`bitmap`	Pointer to a character, which will have the resulting bitmap

Return Code

0: The function succeeded

-1: The function failed. The value in the bitmap is not valid

Comments

#define MCL_DSR 0x01
#define MCL_DTR 0x02
#define MCL_RTS 0x04
#define MCL_CTS 0x08
#define MCL_DCD 0x10
#define MCL_RI  0x20
#define MCL_OP_SET 1
#define MCL_OP_CLEAR 2

SERIAL_SetControlLines

This function is used to modify the control lines (DTR/RTS).

Synopsis

int SERIAL_SetControlLines( int port, 
unsigned char bitmap, 
int op);

Parameter	Description
`port`	Serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.
`bitmap`	Bitmap of control lines to be modified. Input control lines are silently ignored.
`op`	One of MCL_OP_SET/MCL_OP_CLEAR to set/clear the control lines specified in the bitmap parameter

Return Code

0: The function succeeded

-1: The function failed

Comments

The same constants used in SERIAL_GetControlLines() function are also used in this function.

SERIAL_SetMode

Used to set the serial port communication parameters.

Synopsis

int SERIAL_SetMode( int port, 
int baud, 
int numBits, 
SERIAL_Parity parity,
int numStop, 
SERIAL_HSMode hs);

Parameter	Description
`port`	Serial port number (0 based). Specify port 0 to redirect the output to the hsmtrace log.
`baud`	Baud rate.
`numBits`	Number of bits in a character. Should be 7 or 8
`parity`	One of the following: >SERIAL_PARITY_NONE >SERIAL_PARITY_ODD >SERIAL_PARITY_EVEN >SERIAL_PARITY_ONE >SERIAL_PARITY_ZERO
`numStop`	Number of stop bits in a character. Should be 1 or 2
`hs`	Handshake type. Should be one of the following: >SERIAL_HS_NONE >SERIAL_HS_RTSCTS >SERIAL_HS_XON_XOFF

NOTE Serial flow control is not implemented in the current HSM firmware. This value should be set to SERIAL_HS_NONE.

Return Code

0: Mode changed successfully

-1: There was an error