MGSL_PARAMS Structure

The MGSL_PARAMS structure specifies the functional characteristics of a port. This structure is used with the MgslGetParams and MgslSetParams API functions.

WARNING: SOME OPTIONS ARE NOT SUPPORTED BY ALL ADAPTERS!
Check the Adapter Features for which options are supported by a particular adapter.

typedef struct _MGSL_PARAMS
{
    /* common parameters */

    ULONG    Mode;        /* HDLC, async, raw, bisync, monosync */
    UCHAR    Loopback;    /* internal loopback mode flag 1 = enable, 0 = disable */

    /* synchronous mode only parameters */

    USHORT   Flags;
    UCHAR    Encoding;    /* serial encoding */
    ULONG    ClockSpeed;  /* external clock in bits per second, 0 = disable */
    UCHAR    Addr;        /* receive HDLC addr filter, 0xFF = disable */
    USHORT   CrcType;     /* None, CCITT CRC16, CCITT CRC32 */
    UCHAR    PreambleLength;    /* preamble length */
    UCHAR    PreamblePattern;   /* preamble pattern */

    /* Async only parameters */

    ULONG    DataRate;    /* async data rate in bits per second */
    UCHAR    DataBits;    /* 7 or 8 bits */
    UCHAR    StopBits;    /* 1 or 2 */
    UCHAR    Parity;      /* None, Even, Odd */

} MGSL_PARAMS, *PMGSL_PARAMS;

Mode

The mode member determines which serial protocol the port uses. The following modes are supported:

Loopback

If the loopback member is set to a non-zero value then the data on the transmit pin is looped back internally in the adapter to the receive pin. Loopback mode is useful for diagnostics. If Loopback is zero then the adapter behaves normally

Flags

Flags specify functional characteristics of the port. The HDLC_ prefix is present for historical reasons, but unless otherwise specified the option applies to all modes.

Receive Clock Source (mutually exclusive except as noted below)

Transmit Clock Source (mutually exclusive)

DPLL Reference Clock Divisor (mutually exclusive)

The remaining flags can be used in any combination.

HDLC Encoding

The HDLC encoding determines how the TxD and RxD pins represent data bits or logical 1s and 0s. Note that often NRZI_SPACE is simply called NRZI.

ClockSpeed

The clock speed member determines if the adapter generates a data clock on the AUXCLK pin, and at what frequency the clock is generated. A value of 0 disables the AUXCLK pin. Any other value causes the AUXCLK pin to generate a clock at the specified value in bits per second.

The clock is generated by dividing a set clock frequency by an integer time constant. The time constant is related to the data rate by:

SyncLink GT/GT4/AC Adapters:

Time Constant = (14.7456MHz /Data Rate) - 1

SyncLink ISA Adapter (obsolete):

Time Constant = (14.7456MHz /Data Rate) - 1

SyncLink PCI Adapter (obsolete):

Time Constant = (11.0592MHz /Data Rate) - 1

SyncLink SCC Adapter (obsolete):

Time Constant = (3.6864MHz / (2*Data Rate)) - 2

The following adapters require 2 constants A and B

SyncLink PC Card:

Data Rate = (3.6864MHz / ((A + 1) * 2^B)) where A and B are integers, B >= 1

SyncLink Multiport Adapter (obsolete):

Data Rate = (14.7456MHz / (A * 2^B)) where A and B are integers, B >= 1

If the time constant (or A and B) for a particular speed is an integer (or zero) then the specified data rate can be generated exactly. Otherwise the actual data rate is the data rate specified by the time constant rounded up to the next integer value. For relatively low non standard data rates, the resulting error will be small. The clock frequency allows common data rate to be specified exactly: 2400, 9600, 57600, 115200 etc.

Addr

The address field allows HDLC frames to be filtered by hardware based on the 8-bit address field which is the first byte following an opening flag. Frames with the broadcast address of 0xFF are always received regardless of the Addr member value. If Addr is set to 0xFF then all frames are received regardless of the address field value. If an application uses extended addresses then the Addr field should be set to 0xFF and software should examine the address field.

CrcType

Cyclic Redundancy Check used for HDLC mode.

For frames up to 4096 bytes in length, CCITT CRC-16 can detect single and double bit errors, errors of an odd number of bits, error bursts of 16 bits or less, and can detect 99.998% of all errors.

32-bit CRCs can be used for frames up to 64KB, detecting 99.999999977% of all errors.

The CRC selection must match that of the remote system.

Normally, no data is returned when indicating a CRC error to an MgslReceive call. Setting HDLC_CRC_RETURN_CRCERR_FRAME returns the frame data including the trailing CRC value.

Preamble Length and Pattern

The preamble is a bit pattern sent on the transmit pin before sending each HDLC frame. The preamble pattern and length are set with the constants listed below. Use the preamble to synchronize a remote phase locked loop or to guarantee a minimum number of flags between frames. Including the opening and closing flags, 3, 4, 6, and 10 flags can be inserted between frames.

DataRate, DataBits, StopBits, and Parity

These members specify the asynchronous format used when in asynchronous mode. DataRate is the rate in bits per second. DataBits is the number of data bits per character and can be 7 or 8. StopBits is the number of stop bits per character and can be 1 or 2. Parity specifies if a parity bit is added and what kind of parity is used. The parity is specified with one of the following constants: ASYNC_PARITY_NONE, ASYNC_PARITY_EVEN, or ASYNC_PARITY_ODD.