MTP2 API Operation

1. Sample application

The sample application is a good way to get familiar with the FreeTDM interface.

After generating your sample /usr/local/freetdm/conf/freetdm.conf and freetdm.conf.xml files, you can run the sample application:

#>./run_mtp2 -conf freetdm.conf.xml

The sample application will transmit dummy MSU's on each MTP2 link. And listen incoming events from FreeTDM. The source codes for the run_mtp2 application are:

run_mtp2.c
Initialization and configuration.
run_mtp2_test.c
Test functions and event handlers.

2. Initialization

The FreeTDM library is initialised using the following function calls:

ftdm_global_init()
ftdm_global_configuration()
For each span:
ftdm_configue_span_signaling(...);
For each span:
ftdm_span_start(...);

2.1 ftdm_global_init(void)
FreeTDM initialization function. FreeTDM internal variables and parameters are initialized when this function is called.

2.2. ftdm_global_configuration(void)
FreeTDM general configuration function. FreeTDM protocol specific modules are initialized and loaded when this function is called.

2.3.ftdm_configure_span_signaling(ftdm_span_t *span, fio_signal_cb_t sig_cb, ftdm_conf_parameter_t *ftdm_parameters)
Signaling parameters for each span are set using this function.
span: FreeTDM span structure.
sig_cb: Call back function for events.
ftdm_parameters: configuration parameters. Refer to run_mtp2.c:load_config function for an example of how ftdm_parameters is populated.

2.4.ftdm_span_start(ftdm_span_t *span);
Starts the span.

3. API Requests

3.1. ftdm_status_t ftdm_channel_set_sig_status_ex(ftdm_channel_t ftdmchan, ftdm_signaling_status_t sigstatus, ftdm_usrmsg_t usrmsg);

This function is used by the upper layer to request a change of status to MTP2.

sigstatus	usr_msg.raw_id	Description
FTDM_SIG_STATE_UP	SNGSS7_SIGSTATUS_NORM	Request MTP2 link to start alignment procedure in normal mode (SIN).
FTDM_SIG_STATE_UP	SNGSS7_SIGSTATUS_EMERG	Request MTP2 link to start alignment procedure in emergency mode (SIE).
FTDM_SIG_STATE_UP	SNGSS7_SIGSTATUS_FLC_STAT	Request Flow control status.
FTDM_SIG_STATE_UP	SNGSS7_SIGSTATUS_LOC_PROC_UP	Indicate to remote side that local processor is UP.
FTDM_SIG_STATE_SUSPEND	SNGSS7_SIGSTATUS_LOC_PROC_DN	Indicate to remote side that local processor is DOWN.

Example:

/* Request MTP2 to start alignment in Emergency mode */
static void request_mtp2_connect(ftdm_channel_t *ftdmchan)
{
	ftdm_usrmsg_t usrmsg;
	memset(&usrmsg, 0, sizeof(usrmsg));
	
	usrmsg.raw_id = SNGSS7_SIGSTATUS_EMERG;
	ftdm_channel_set_sig_status_ex(ftdmchan, FTDM_SIG_STATE_UP, &usrmsg);
	return;
}

3.2. ftdm_channel_call_indicate_ex(ftdm_channel_t ftdmchan, ftdm_channel_indication_t indication, ftdm_usrmsg_t usrmsg);

This function is used by the upper layer to request maintenance tasks to MTP2.

usrmsg.raw_id	Description
SNGSS7_REQ_FLUSH_BUFFERS	Request MTP2 to flush current buffers.
SNGSS7_REQ_CONTINUE	Continue.
SNGSS7_REQ_RETRV_BSN	Retrieve the current Backward Sequence Number.
SNGSS7_REQ_RETRV_MSG	Retrieve messages based on Backward Sequence Number.
SMGSS7_REQ_DROP_MSGQ	Request MTP2 to drop transmit queue.

example:

/* Request MTP2 to retrieve messages based on Backward Sequence Number */
static void request_mtp2_retrv_msg(ftdm_channel_t *ftdmchan, uint16_t bsn)
{
	ftdm_usrmsg_t usrmsg;
	uint16_t *p_bsn;

	p_bsn = ftdm_calloc(1, 0, sizeof(uint16_t);
	ftdm_assert(p_bsn, "Failed to allocate memory");

	memset(&usrmsg, 0, sizeof(usrmsg));

	*p_bsn = bsn;
	ftdm_usrmsg_set_raw_data(&usrmsg, p_bsn, 2);
		
	usrmsg.raw_id = SNGSS7_REQ_RETRV_MSG;
	ftdm_channel_indicate(ftdmchan, FTDM_CHANNEL_INDICATE_RAW, &usrmsg);
	return;
}

3.3. ftdm_channel_write(ftdm_channel_t ftdmchan, void data, ftdm_size_t datasize, ftdm_size_t datalen);

Used to transmit MSU's.

example:

/* Request MTP2 to transmit MSU */
static void request_mtp2_transmit(ftdm_channel_t *ftdmchan, void* data, uint32_t datalen)
{
	if (ftdm_channel_write(ftdmchan, data, MAX_MSU_SIZE, &datalen) != FTDM_SUCCESS) {
		fprintf(stderr, "Failed to write data to channel\n");
	}
	return;
}

4. API Events

All indications from the MTP2 layer will result in a signal callback function that was previously registered using ftdm_span_configure.

event_id	Event Type
FTDM_SIGEVENT_SIGSTATUS_CHANGED	Signalling status changed
FTDM_SIGEVENT_RAW	Response to a maintenance request
FTDM_SIGEVENT_IO_INDATA	Incoming data received

4.1 Signalling status changed

Status	Reason	Description
FTDM_SIG_STATE_UP	SMGSS7_REASON_UNUSED	MTP2 Link aligned
FTDM_SIG_STATE_UP	SNGSS7_REASON_END_FLC	End of Flow Control
FTDM_SIG_STATE_UP	SNGSS7_REASON_REM_PROC_UP	Remote Processor Up
FTDM_SIG_STATE_SUSPENDED	SNGSS7_REASON_START_FLC	Start of Flow Control. MTP2 Transmit Threshold reached, upper layer should stop transmitting MSU's and request Flow Control Status until end of Flow Control.
FTDM_SIG_STATE_SUSPENDED	SNGSS7_REASON_REM_PROC_DN	Remote processor down.
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_SM	Upper Layer requested a Disconnect
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_SUERM	SUERM Threshold reached
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_ACK	Excessive delay of acknowledgements from remote MTP2
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_TE	Failure of Terminal Equipment
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_BSN	2 of 3 Unreasonable BSN
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_FIB	2 of 3 Unreasonable FIB
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_CONG	Excessive periods of congestion
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_LSSU_SIOS	SIO/SIOS received in link state machine
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_TMR2_EXP	Timer T2 expired
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_TMR3_EXP	Timer T3 expired
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_LSSU_SIOS_IAC	SIOS received during alignment
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_PROV_FAIL	ERM threshold reached
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_TMR1_EXP	Timer T1 expired
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_LSSU_SIN	SIN received in in-service state
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_CTS_LOST	Disconnect from L1
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_DAT_IN_OOS	Request to transmit data in OOS
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_DAT_IN_WAITFLUSHCONT	Request to transmit when MTP2 is waiting for flush/continue directive
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_RETRV_IN_INS	Request message retrieval request while in-service state
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_CON_IN_INS	Request connect request in in-service state
FTDM_SIG_STATE_DOWN	SNGSS7_REASON_UPPER_SAP_DIS	Received request to disable SAP.

4.2 Response to maintenance request

Id	Description
SNGSS7_IND_RETRV_BSN	Response to a SNGSS7_REQ_RETRV_BSN
SNGSS7_IND_DATA_MORE	Response to a SNGSS7_REQ_RETRV_MSG, there are more frames to come
SNGSS7_IND_DATA_NO_MORe	Response to a SNGSS7_REQ_RETRV_MSG, this is the last frame

4.3 Incoming data received

Incoming MSU was received.