Intell NetStrIntel NetStructure® SS7 Protocolsucture Software Environment Programmer's Manual
Intell NetStrIntel NetStructure® SS7 Protocolsucture Software Environment Programmer's Manual
Issue 5
Page 1
Revision History
ISSUE
DATE
CHANGES
18-Jul-95
19-Feb-97
29-May-99
02-Aug-03
05-Dec-05
Disclaimer
The product may contain design defects or errors known as errata, which may cause the product to deviate from
published specifications.
Information in this document is provided in connection with Intel products. No license, express or implied, by estoppel
or otherwise, to any intellectual property rights is granted by this document. Except as provided in Intel's Terms and
Conditions of Sale for such products, Intel assumes no liability whatsoever, and Intel disclaims any express or implied
warranty, relating to sale and/or use of Intel products including liability or warranties relating to fitness for a particular
purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Intel products are
not designed, intended or authorized for use in any medical, life saving, or life sustaining applications or for any other
application in which the failure of the Intel product could create a situation where personal injury or death may occur.
Intel may make changes to specifications and product descriptions at any time, without notice.
Intel and Intel NetStructure are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United
States and other countries.
* Other names and brands may be claimed as the property of others.
Copyright 1995 - 2005 Intel Corporation. All rights reserved. No part of this document may be copied, or reproduced in
any form, or by any means without prior written consent of Intel.
Issue 5
Page 2
Contents
1 INTRODUCTION ......................................................................................................5
2 BASIC CONCEPTS ..................................................................................................6
2.1 Modules ........................................................................................................6
2.2 Module Identifiers..........................................................................................6
2.3 Messages......................................................................................................7
2.4 Message Queues..........................................................................................7
2.5 Distributed Modules ......................................................................................8
2.6 Library Functions ..........................................................................................9
2.7 System Initialisation ....................................................................................10
2.8 Attaching to the message passing environment..........................................10
2.9 System Congestion .....................................................................................11
3 PROGRAM EXECUTION .......................................................................................12
3.1 Windows* ....................................................................................................12
3.2 Running software as a Windows service.....................................................13
3.2.1 Installing the Service .......................................................................13
3.2.2 Uninstalling the Service ...................................................................14
3.2.3 Running the Service manually .........................................................14
3.3 Linux* ..........................................................................................................15
3.4 Solaris*........................................................................................................15
4 MESSAGE REFERENCE.......................................................................................16
4.1 Message Format .........................................................................................16
4.1.1 MSG Message Structure .................................................................16
4.1.2 Header Fields ..................................................................................16
4.1.3 Parameter Field ...............................................................................17
4.2 Message Specifications ..............................................................................18
4.2.1 Congestion Messages .....................................................................18
5 LIBRARY FUNCTIONS ..........................................................................................19
5.1 GCT Library Functions ................................................................................19
5.1.1 GCT_send .......................................................................................19
5.1.2 GCT_receive ...................................................................................20
5.1.3 GCT_grab........................................................................................21
5.1.4 GCT_set_instance...........................................................................22
5.1.5 GCT_get_instance...........................................................................23
5.1.6 getm ................................................................................................24
5.1.7 relm .................................................................................................25
5.1.8 GCT_link .........................................................................................26
5.1.9 GCT_unlink......................................................................................26
5.1.10 GCT_partition_congestion .............................................................27
5.1.11 confirm_msg ..................................................................................28
5.2 Message Parameter Management..............................................................29
5.2.1 rpackbytes .......................................................................................29
5.2.2 runpackbytes ...................................................................................30
6 HOST UTILITIES....................................................................................................31
Issue 5
Page 3
Issue 5
Page 4
1 INTRODUCTION
The range of Intel NetStructure products includes a number of software modules
for implementation of SS7 and SIGTRAN signalling protocol stacks. The
architecture is multi-tasking, using message passing to communicate between
tasks.
Each module in the system is implemented as a separate task within the chosen
operating environment. A module implements either a layer within the protocol
stack, a user part or some other functional entity within the system. In general, a
module supports multiple internal instances within a single process (for example
multiple links, multiple circuits or multiple transactions are each handled by a
single process). The architecture supports multi-processor operation with modules
being distributed between different processors.
For software portability, each module makes a minimum demand on the host
operating system. Most modules require just 7 functions to be provided by the
operating system, these are required for inter-process communication and
memory allocation. This approach makes the software easy to port to different
platforms and operating environments. In addition, the use of message passing
between tasks, and therefore protocol layers, means that it is possible for different
layers to run on different processors if required.
All that changes between different operating systems is the implementation of
these library functions tailored to the particular environment.
This document describes the operating environment for the protocol modules and
presents a utility program - gctload - which automatically creates and initialises
the required environment for a number of operating systems.
Issue 5
Page 5
2 BASIC CONCEPTS
This chapter introduces the basic concepts and terminology that will be used
throughout the remainder of the manual.
2.1 Modules
A module is an implementation of a particular layer in the protocol stack (e.g.
MTP2, MTP3), a particular user part (e.g. ISUP, SCCP) or a collection of other
functionality which fits together as a logical entity. A module may be part of the
Intel NetStructure SS7 Protocols product range or a User-supplied module.
Each module in the system runs as a separate task, process or program
(depending on the type of operating system). The module is identified by a
Module Identifier and communicates with other modules in the system by
sending Messages to a Message Queue belonging to the destination module. A
set of Library Functions is the only operating system specific code used by a
module.
A module handles multiple internal instances of the functional entity associated
with the module (e.g. MTP2 module handles multiple signalling links, the MTP3
module handles multiple link sets and multiple routes, the ISUP module handles
multiple circuits).
2.2 Module Identifiers
Each module has a module identifier (module_id) which is a logical number in the
range 0 to 255. It is used to identify modules within the system for the purposes of
inter-process communication. To send a message to another process the sending
module uses the module identifier of the destination process. To receive a
message from a module's own message queue it uses its own module identifier.
Some modules operate with a fixed module identifier whilst others allow the
module identifier to be specified at run-time.
The module identifiers of other modules with which a module will communicate is
usually a run-time configuration option.
The module identifier is a logical value, it is not the same as the task_id or process
id (pid) which is usually allocated automatically by the operating system when a
process is created.
The inter-process communication mechanism usually uses the module identifier as
an index to an array of message queue pointers to provide an efficient mechanism
to quickly access the correct message queue. This feature can also be used to
allow messages destined for a particular module to be re-directed to an alternative
message queue belonging to another module.
Issue 5
Page 6
Issue 5
Page 7
Issue 5
Page 8
GCT_receive
GCT_grab
GCT_set_instance
GCT_get_instance
GCT_partition_congestion
getm
relm
GCT_link
GCT_unlink
confirm_msg
The syntax for each of these functions is described in the following chapter. Their
usage is described below.
A module wishing to send a message to another module will first allocate an MSG
structure using the getm function. At this stage it is necessary to decide whether
or not a confirmation message will be required and initialise the rsp_req field
accordingly. Once all the message parameters have been entered into the MSG
the module calls GCT_send to send the message to the destination module. If the
GCT_send function fails to send the message the sending module must release
the message back to the system using the relm function (although this will only
happen when the system is incorrectly configured). When multiple destination
processors are used the module sending the message must call
GCT_set_instance prior to calling GCT_send in order to write the destination
module instance into the message.
The destination module will receive the message from its own message queue
using either the GCT_receive or GCT_grab functions (depending on whether it
wishes to block or not if no messages are available). It then processes the
message. When multiple source processors are used the module receiving the
message should call GCT_get_instance after calling GCT_receive or GCT_grab
in order to read the source module instance from the message.
Issue 5
Page 9
When the receiving module has finished processing the message it carries out one
of two possible courses of action depending on whether or not a confirmation is
required. If no confirmation is required then the message is released back to the
system using the relm function. If a confirmation is required then a status value is
written into the message header, the message type is changed (bit 14 is cleared)
and the message is sent back to the original sending module using the GCT_send
function. On receipt of the confirmation the original sending module (after
inspecting the status) releases the message back to the system using the relm
function.
In this way it is ensured that each message will eventually always be released
back to the system.
2.7 System Initialisation
System initialisation requires first that a pool of message buffers is created for
subsequent inter-process communication. Secondly, that a message queue is
created for each module that will run and that any message re-direction for
modules that are running remotely is initialised. Then all process can be started.
A program gctload exists to handle this initialisation sequence. It reads input from
a text file called system.txt, carries out all system initialisation and starts up all
processes. It then remains dormant until it receives a signal from the operating
system to shutdown. Then it terminates all processes that it started and releases
any system resources back to the system in a controlled manner.
The basic operation of the gctload program, and the format of the text file it uses,
is described in 6.1 . The gctload is available for a number of operating systems.
See section 3 for detail specific of specific operating systems.
2.8 Attaching to the message passing environment
Normally the gctload module, which establishes message queues and preallocates memory from the system for the messages used by all tasks is used to
initiate all user modules. These structures are released on termination of gctload,
hence the tasks that communicate using these mechanisms and the user tasks
are also terminated.
If the user chooses to run applications independently he needs to confirm that the
system is available at before using system resources The GCT_link library
function can be used to obtain this confirmation See section 5.1.8 for details.
The user must also ensure that the application does not attempt to access system
resources after the GCT environment has been terminated. The GCT_unlink
library function can be used to release all system resources. See section 5.1.9 for
details.
Issue 5
Page 10
If the user wishes to terminate and re-start an application this can be achieved by
calling GCT_unlink from the old instance of the application prior to termination
and the calling GCT_link from the new application before using system resources.
2.9 System Congestion
When the host software is first run, a specified number of messages is allocated
from host system resources. These messages are available for inter-task
communication.
Application read messages from their own input queue, extract the information
from these messages then release the original message structure back to the
system. Hence, under normal operating conditions, the host application works to
ensure that its queue is almost empty, and that all the messages are available.
If, however, more messages are received than the system can handle then a
backlog of messages in input queues will build up. Possible causes include input
being received at a faster rate than can be processed by the output device or the
system being unable to process received input in at the required rate.
The message handling environment monitors the number of allocated messages
available as a percentage of the total message pool. If this percentage exceeds a
configurable congestion onset threshold, the host is said to be in a congested
state
When the message handling environment detects a state of congestion it sends a
notification message to a configured congestion-handling module. This module
is responsible for taking actions to slow down the source of system congestion.
When the number of allocated messages available as a percentage of the total
message pool returns to a configurable congestion abatement threshold, the
host is said to be leave the a congested state. A SYS_MSG_CONGESTION
message is sent to the congestion-handling module.
The congestion handling parameters are set as command line parameters for the
gctload module. See section 6.1.1 for details.
For most system configurations use of message-based congestion handling is
recommended but the system congestion status may also be obtained using the
GCT_partition_congestion function. See section 5.1.10 for details.
Issue 5
Page 11
3 PROGRAM EXECUTION
3.1 Windows*
The gctload program should be executed from the directory containing the
System Configuration File. An alternative System Configuration File filename
(instead of system.txt) can be selected using the command line option
-c<filename>.
To run the system in a separate console use:
start gctload -csystem.txt
The mechanism to shutdown the system depends on how the software was
started up. If the system was run in a separate console all processes can be
stopped in one operation by pressing CTRL-C. If the system was run in the current
console enter CTRL-C to stop gctload and then stop each other process
individually using the Task Manager.
Command line arguments can be used following the FORK_PROCESS command
although there may be some limitations to the symbols that are permitted.
Note that the filename of the binary file on each FORK_PROCESS command line
must include the .exe file extension.
Issue 5
Page 12
Where
<service>
<gctload>
Issue 5
Page 13
The locations of the required executables have to be specified with full pathnames
including the drive letter. Pathnames that contain spaces are not supported.
When the service is installed, by default the startup mode is set to mode 'manual'.
To cause it to be automatically invoked at boot time it must be explicitly configured
to 'automatic' mode. This is achieved by running the services tool and setting the
startup option to "automatic".
Under Windows NT the services tool can be found within the Control Panel. Under
Windows 2000, Windows XP and Windows 2003 the services tool can be found
within the Administrative Tools section of the control panel.
When starting gctload as a service, it is not possible to pass command line
parameters directly to gctload. It is therefore recommended that NUM_MSGS and
CONG_MSG system.txt commands are used for configuring the GCT messaging
environment. See sections 6.1.9 and 6.1.10 for details.
3.2.2 Uninstalling the Service
The service is also removed using the executable servcfg.exe using the syntax
given below.
servcfg.exe remove
The service executable can then be removed from the system32 directory.
del servcfg.exe
Issue 5
Page 14
3.3 Linux*
The gctload program should be executed from the directory containing the
System Configuration File.
An alternative System Configuration File filename (instead of system.txt) can be
selected using the command line option -c<filename>.
To shutdown the system it is first necessary to determine the process id (pid) of
the gctload process. Then enter the following command:
kill <gctload_pid>
The values are read by the kernel at boot time so there is no need to re-build the
kernel, just reboot the system.
The default values for these are given in /usr/include/sys/msg.h.
The new values for these parameters should be set to at least the following
values. There may be other users of these resources so the actual value may
need to be greater than the values shown.
msgmni = At least the number of 'LOCAL' entries in system.txt.
msgtql = At least the number of MSGs in the system.
Issue 5
Page 15
4 MESSAGE REFERENCE
4.1 Message Format
4.1.1 MSG Message Structure
A message consists of a fixed header field and a variable length parameter field:
typedef struct msg
{
HDR
unsigned short
long
} MSG;
hdr;
len;
param[80]
hdr
short
short
char
char
short
char
char
long
type;
id;
src;
dst;
rsp_req;
hclass;
status;
err_info;
*next;
Issue 5
Page 16
type: The type field is used to distinguish between different messages. It uniquely
identifies the format of the remainder of the message and in particular the format
of the message parameter area.
id: The id field allows modules which handle multiple internal instances of a single
entity (such as a signalling link) to distinguish which entity the message is destined
for.
src: The src field contains the module identity of the module which issued the
message.
dst: The dst field contains the module identity of the module which the message is
destined.
rsp_req: The rsp_req field is used by the originator of a message to indicate
whether or not it requires confirmation from the receiving module that the message
has been received.
If the sending module requires confirmation it sets a bit in the rsp_req field prior to
sending the message. Which bit to set is determined by the least significant nibble
of the module's own module id (as written in the src field). For example if the
module id is 0x36 and message confirmation is required, the user would set bit 6
in the rsp_req field so rsp_req would equal 0x0040.
If message confirmation is not required then the rsp_req field should be set to
zero.
The confirmation message takes the same format as the request message but
uses a different type value. The type value for a confirmation message is derived
from the type value in the request message by clearing bit 14.
hclass: This field is reserved for future use it is assigned by getm() and must not
be modified.
status: This field is used for confirmation messages and indications to indicate the
status associated with the message. A value of 0 in a confirmation message
usually indicates success.
err_info: This field is used in some confirmation and indication messages to
supplement the status field and provide additional information
next: This field is reserved for future use and should not be used.
4.1.3 Parameter Field
The parameter field can contain 0 to 320 bytes of data. The data is stored in the
parameter field in a host independent format. The contents and format of
messages parameter field are defined in the various Programmers Manuals.
Issue 5
Page 17
MEANING
SYS_MSG_CONGESTION (0x0001)
0
Sending module's module_id
congestion-handling module (0x20)
0
0
congestion_status
0
0
Description:
This message is sent to the congestion-handling module to report a change in
system congestion state.
Parameter Description:
congestion_status
The updated status of system congestion
Value
Mnemonic
Meaning
NO_CONGESTION
CONGESTION
Issue 5
Page 18
5 LIBRARY FUNCTIONS
5.1 GCT Library Functions
5.1.1 GCT_send
Synopsis:
Function to send the message pointed to by h to the specified module_id.
Prototype:
int GCT_send(unsigned int module_id, HDR *h);
Return Value:
Returns zero on success, non-zero otherwise.
If the function does not return success then the calling program must release the
message back to the system using relm().
Parameters:
module_id - The destination module id. This will usually be the same as the value
contained in the hdr.dst field of the message.
h - A pointer to the HDR structure at the start of the MSG to be sent. This
parameter should always point to a buffer allocated using getm().
Description:
This function uses module_id to determine which message queue the message
should be sent to and sends the message. A success return value implies that the
message has been sent to the message queue belonging to the destination
process.
Issue 5
Page 19
5.1.2 GCT_receive
Synopsis:
Function to wait until the next message for module_id is available and return a
pointer to the message.
Prototype:
HDR *GCT_receive(unsigned int module_id);
Return Value:
A pointer to the received message on success, 0 on failure.
Parameters:
module_id - The module's own module id.
Description:
This function uses module_id to determine which message queue to receive from.
If the message queue contains a message then a pointer to the first message is
returned. Otherwise the function suspends the calling task until a message is
available.
After processing, the message returned by the GCT_receive function must either
sent back to the sending module (as a confirmation message) or released back to
the system using relm().
The only difference between GCT_receive and GCT_grab is whether to block or
not when no messages are available.
Issue 5
Page 20
5.1.3 GCT_grab
Synopsis:
Function to determine whether there is a message ready for module_id and return
a pointer to the message. If no message is ready then the function returns
immediately.
Prototype:
HDR *GCT_grab(unsigned int module_id);
Return Value:
A pointer to the received message on success or 0 if there are no messages
waiting.
Parameters:
module_id - The module's own module id.
Description:
This function uses module_id to determine which message queue to receive from.
If the message queue contains any messages then a pointer to the first message
is returned. Otherwise the function immediately returns zero.
After processing, the message returned by the GCT_grab function must either
sent back to the sending module (as a confirmation message) or released back to
the system using relm().
The only difference between GCT_receive and GCT_grab is whether to block or
not when no messages are available.
Issue 5
Page 21
5.1.4 GCT_set_instance
Synopsis:
Function to write the module instance into the message pointed to by h.
Prototype:
int GCT_set_instance(unsigned int instance, HDR *h);
Return Value:
Returns zero on success, non-zero otherwise (currently no failure conditions are
defined).
Parameters:
instance - The destination module instance.
h - A pointer to the HDR structure at the start of the MSG.
Description:
Writes the destination module instance into the message. This function should be
called prior to calling GCT_send by the module sending the message.
The destination module instance is used when messages are sent from one
processor to another processor. It determines which destination processor the
message is sent to.
Examples of the use of this function are as follows:
a) When sending messages to one of several boards. In this case the module
instance is the board_id.
b) When sending messages to one or other Signalling Interface Unit (SIU)
from an SIU pair. In this case the module instance is 0 (SIUA) or 1 (SIUB).
Issue 5
Page 22
5.1.5 GCT_get_instance
Synopsis:
Function to recover the module instance from the message pointed to by h.
Prototype:
unsigned int GCT_get_instance(HDR *h);
Return Value:
Returns the module instance read from the message.
Parameters:
h - A pointer to the HDR structure at the start of the MSG.
Description:
Recovers the source module instance from a received message. This function
should be called after return from GCT_receive or GCT_grab.
The source module instance is used when messages are received from a number
of processors by the local module. It identifies the source processor at which the
message originated.
Examples of the use of this function are as follows:
a) When receiving messages from one of several boards. In this case the
module instance is the board_id.
b) When receiving messages from one or other Signalling Interface Unit (SIU)
in an SIU pair. In this case the module instance is 0 (SIUA) or 1 (SIUB).
Issue 5
Page 23
5.1.6 getm
Synopsis:
Function to allocate an MSG and initialise given fields in the message header.
Prototype:
MSG *getm( unsigned short type, unsigned short id,
unsigned short rsp_req, unsigned short len);
Return Value:
A pointer to the allocated message buffer message or 0 if no buffers available.
Parameters:
type - The message type, this is written to the hdr.type field of the message
before the function returns.
id - The id value, this is written to the hdr.id field of the message before the
function returns.
rsp_req - The rsp_req value, this is written to the hdr.rsp_req field of the
message before the function returns.
len - The number of bytes that will be used in the parameter area of the message.
This is written to the len field of the message before the function returns.
Description:
This function allocates a message buffer from the buffer pool and initialises the
type, id, rsp_req and len fields of the message to the specified values.
The function is used to allocate a message for subsequent inter-process
communication where it will be sent to the destination process. On return from the
function is the calling functions responsibility to initialise the hdr.src, and hdr.dst
fields and the parameter area of the message prior to calling GCT_send().
Issue 5
Page 24
5.1.7 relm
Synopsis:
Function to release a message that has previously been allocated by getm(),back
to the system.
Prototype:
int relm(HDR *h);
Return Value:
Zero on success; non-zero otherwise.
Parameters:
h - A pointer to the HDR structure at the start of the MSG.
Description:
Returns a message buffer allocated by getm() to the system buffer pool.
Each message allocated must be returned once (and only once) to the system. It
does not need to be returned by the same process that allocated it.
Issue 5
Page 25
5.1.8 GCT_link
This function can be used to attach to the GCT environment. It also returns a
notification as to the state of the GCT environment.
Note: this function is not normally required because it is achieved transparently to
the application software during the first call to one of the GCT_grab, GCT_receive
or getm library functions. See section 2.8 for details.
Prototype:
int GCT_link(void);
Return Value:
Returns zero on success
Non zero is returned on failure, indicating that gctload is not running (GCT
environment is not available).
5.1.9 GCT_unlink
The GCT_unlink function allows and application to detach from the message
passing environment
Note: this function is not normally required because it is achieved transparently the
when the GCT module terminates the environment and all applications on
termination. See section 2.8 for details.
Prototype:
int GCT_unlink(void);
Return Value:
Always returns zero.
Issue 5
Page 26
5.1.10 GCT_partition_congestion
This function can be used to determine the congestion status of the GCT
environment.
Normally use of message based congestion handling is recommended see
section 2.9 for details.
Prototype:
int GCT_partition_congestion (int partition);
Parameter:
The partition parameter must always be set to 0.
Return Value:
The current system congestion state.
Value
Mnemonic
Meaning
NO_CONGESTION
CONGESTION
Issue 5
Page 27
5.1.11 confirm_msg
Function to confirm a message once it has been handled.
If the sending layers response required bit is set then a confirmation is returned
otherwise the MSG is released.
Prototype:
int confirm_msg(MSG *message);
Parameter:
The message is a pointer to the message to be confirmed.
Return Value:
The function always returns 0.
Issue 5
Page 28
Return Value:
None.
Parameters:
dest - pointer to the destination buffer
dest_byte_offset - offset from the start of the destination buffer to store data
value - the value to be put into the buffer
bytecount - the number of significant bytes to take from value.
Description:
Packs the requested number of bytes into a buffer in a machine independent
manner for sending to another module, regardless of byte ordering on either
processor.
Example:
rpackbytes(dest, 10, value, 2);
This call will use the least significant 2 bytes of the value and store the resulting
data starting at location dest + 10. The least significant byte of value will be written
to dest + 11 and the next most significant byte to dest + 10.
Issue 5
Page 29
5.2.2 runpackbytes
Synopsis:
Function to extract bytes from machine independent format.
Prototype:
unsigned long runpackbytes(unsigned char *src, int src_byte_offset,
int bytecount);
Return Value:
The numeric value unpacked from the buffer.
Parameters:
src - pointer to the source buffer
src_byte_offset - offset from the start of the message buffer to retrieve data
bytecount - the number of bytes to take from the message.
Description:
Unpacks the requested number of bytes from a buffer, regardless of byte order on
the processor.
Example:
result = (u16)runpackbytes(src, 10, 2);
This call will retrieve the least two significant bytes from the buffer src and return
the value as a u16. The u16 will be formed by src + 11 as the least significant byte
and src + 10 as the most significant byte.
Note : The user should cast the return value to the required type.
Issue 5
Page 30
6 HOST UTILITIES
6.1 gctload
The program gctload is run to initialise the system environment. It reads the
system configuration from a file called system.txt. This is a user configurable file
containing details of all the module identifiers known to the system, details of
whether they are local modules or remote modules accessed by a local module
(message redirection) and lists the command line for all processes to be started by
gctload.
gctload builds a pool of message buffers for subsequent use by the getm() and
relm() functions. The user may modify the size of this buffer pool by the use of a
command line parameter if required.
gctload creates a message queue for each of the local module identifiers. (It
subsequently expects a process to service each message queue otherwise
messages will be written to message queues and never read causing a loss of
system messages).
It initialises the message queue look-up table so that messages destined for
modules that do not exist locally are re-directed to a message queue for a module
which does exist locally.
Having created the system environment, gctload proceeds to spawn all processes
listed in the system configuration file in. It then remains dormant until it receives a
signal from the user to shutdown the system.
To shut down the system it terminates any processes that it created and releases
all system resources back to the operating system.
6.1.1 Command Line Parameters
Syntax:
gctload [
Example:
gctload cmyconfig.txt m1000 Co500 Ca200 Ci0x
The message pool size is the number of message that are to be available to all
modules. The default value is 200 and the supported value is maximum 65000.
The system config file specifies which file to use as the system configuration file.
This parameter is normally omitted and the default, system.txt used. See section
6.1.5 for details.
Issue 5
Page 31
Description:
In this mode gctload can be used as a diagnostic utility to examine the usage of
operating system resources for messages and message queues. When a host is
running (having already started gctload), run gctload a second time with a -t1
switch to display message statistics to the console. This causes gctload to print
the current system status in the following format:
GCTLOAD System status:
MSGs in system:
MSGs allocated:
MSGs free:
Maximum MSGs allocated:
Out of MSG count:
Congestion module Id:
Congestion onset:
Congestion abate:
Congestion status:
Congestion count:
200
4
196
6
0
0xb0
100
20
0
0
Issue 5
Page 32
Description:
The t2 option causes gctload to print a list of all the currently allocated messages
to the console. These messages are shown in the same format as described for
the s7_log and s7_play programs (see section .
An example output is shown below:
M-t7680-i0000-fcf-d20-s00
M-t7681-i0000-fcf-d20-s00
M-t7203-i0000-fcf-d71-s00
The printout above indicates that there are messages sent to a destination task
0xef in the IPC system. Under normal operation, the message queues for
destination tasks should either be empty or contain a small number of messages.
If this is not the case, this may be due to one of the following reasons:
No active task has been set to read messages for the listed destination
The destination task may have stopped reading from its message queue or
may have stopped running.
There may be a missing REDIRECT statement in the hosts system.txt file to
redirect messages from the listed destination to a running task.
6.1.4 Terminate Session
Syntax:
gctload x
Description:
This option causes gctload to terminate an existing session.
Issue 5
Page 33
* (Hexadecimal)
* (Decimal)
<module_id>
Example:
LOCAL
0x20
Description:
This command causes gctload to create a message queue and associate the
queue with the given module_id.
These commands should appear at the start of the System Configuration file. One
entry should appear for each local module that will run in the system. The module
identifier, <module_id>, must be in the range 0 .. 255 and must not have already
been declared. Usually the module_id is entered in hexadecimal format.
Issue 5
Page 34
Example:
REDIRECT
0x22
0x20
Description:
This command causes messages destined to <new_module_id> to be redirected
to <existing_module_id>. The <existing_module_id> must have already been
declared as a local module.
Messages for many module identifiers may be re-directed to a single module. A
separate command line should be used in each case.
Typical use for this command is to redirect messages intended for processes that
are running on a remote board via a local process which is responsible for
transferring the message to the remote board.
6.1.8 Spawn a process
Synopsis:
Command to spawn process.
Syntax:
FORK_PROCESS
<process_path_name> { <parameters> }
Example:
FORK_PROCESS
/mydir/BIN/myproc
* Startup my process
Description:
This command will cause the specified process to be spawned once the system
environment has been created. Under some operating systems it is possible to
specify command line parameters for the process to be forked.
A process does not have to be spawned in the configuration file providing it is run
after gctload and its module identifier has been declared as local. The advantage
of using the configuration file is that all processes spawned by gctload can be
shutdown in a controlled manner using a single command.
Issue 5
Page 35
Example:
NUM_MSGS 2000
Description:
This command configures the number of messages globally allocated for use
within the GCT environment. This is the only way to configure the size of the
message pool if gctload is being run as a service under Windows
6.1.10 Configure System Congestion Parameters
Synopsis:
Configures the congestion parameters for the GCT environment.
Syntax:
CONG_MSG <module Id> <onset threshold> <abatement threshold >
Example:
CONG_MSG 0x21 50 10
Description:
This command configures the behaviour of the GCT environment congestion
reporting system. See section 2.9 for details. The following parameters can be
configured using this message.
The congestion module Id specifies the congestion-handling module ID. This
replaces the -Ci option for gctload.
The congestion onset threshold specifies the percentage of the total number of
available messages that must be allocated before the system will start congestion
procedures. This replaces the -Co option for gctload.
The congestion abatement threshold. specifies the percentage of the total
number of messages that must be available before the system will terminate
congestion procedures. This replaces the -Ca option for gctload.
Issue 5
Page 36
6.2 s7_log
Synopsis:
This is a console application program that receives messages and displays these
as text on the host console. Maintenance and status events are interpreted as text,
other messages are displayed in hexadecimal format.
Syntax:
s7_log [ m<module_id> -o<options> -f<filename> ]
<module_id> is the unique module identifier assigned to the s7_log task for the
IPC environment. Any message sent to this module ID will be displayed by s7_log
as text on the host console. This may be entered as decimal or hexadecimal with a
0x prefix. If not specified, s7_log will use a module id of 0xef. The module ID
assigned to s7_log must have a corresponding LOCAL entry in the hosts
system.txt file and must not be in use by any other process on the host.
<options> is a 16 bit value that specifies the type of message reporting that will
occur. If not specified, a value of 0xaf0d is used. Each bit set to 1 enables
reporting of a particular message group or parameter field as described in the
following table:
Issue 5
Page 37
Bit
Function
5,6,7
10
11
12
13
14
15
<filename> optionally specifies a file that will have all screen output written to.
This file will be created if this option is specified, or an existing file (with the same
name) will be overwritten. The data is stored in the file in ASCII format.
Example:
For example, the command line to run s7_log as module ID 0xef and enable all
tracing options would be:
s7_log -m0xef o0xff1f
Issue 5
Page 38
Description
A typical output from s7_log is shown below:
S7_LOG: System 7 Message monitor (C) 1998-2005 Intel Corp.
==========================================================
S7_log : mod ID=0xef, options=0xaf0d
S7L:I00 RSI_MSG_LNK_STATUS : Link 0 now down
S7L:I00 RSI_MSG_LNK_STATUS : Link 0 now up
S7L:I01 RSI_MSG_LNK_STATUS : Link 0 now down
S7L:I01 RSI_MSG_LNK_STATUS : Link 0 now up
S7L:I00 LIU Status : id=0 IN SYNC
S7L:I00 LIU Status : id=0 PCM OK
S7L:I00 Level 2 State : id=0 INITIAL ALIGNMENT
S7L:I00 LIU Status : id=0 IN SYNC
S7L:I00 LIU Status : id=0 PCM OK
S7L:I01 Level 2 State : id=0 INITIAL ALIGNMENT
S7L:I00 Level 2 State : id=0 ALIGNED READY
S7L:I00 Level 2 State : id=0 IN SERVICE
S7L:I00 MTP Event : linkset_id/link_ref=0000 Changeback
S7L:I00 MTP Resume, dpc=00000001
S7L:I00 M t0708 i0000 f23 d1d s00 p000000007fff
S7L:I00 M t0708 i0000 f23 d1d s00 p00007fff0000
Each field contains the value of the corresponding message field in hexadecimal.
Issue 5
Page 39
6.3 s7_play
Description
s7_play is a console application that will read commands specified as ASCII text in
a file an execute these commands. The command may either specify that a
message is sent to a destination process or that a delay is applied before the next
command is executed.
Syntax:
s7_play m<module_id> -f<filename>
<module_id> is the unique module identifier assigned to the s7_play task for the
IPC environment. Any message sent to this module ID will be displayed by s7_log
as text on the host console. This may be entered as decimal or hexadecimal with a
0x prefix. If not specified, s7_play will use a module id of 0xef. The module ID
assigned to s7_play must have a corresponding LOCAL entry in the hosts
system.txt file and must not be in use by any other process on the host.
<filename> specifies the text file containing the commands to be executed by
s7_play.
Example:
For example, to run s7_play as module ID 0x2d and take commands from a file
cmd.txt.
s7_play m0x2d fcmd.txt
Command File:
Each line of the text file must begin with one of the following command specifiers:
Character
Function
Send a message
Delay
The delay function takes a single parameter specifying the delay in either
milliseconds or seconds, as follows:
D-s0001
D-m0001
Issue 5
Page 40
The send message function allows the fields of the message being sent to be
specified in the following format:
M-I<inst>-t<type>-i<id>-f<src>-d<dst>-r<rsp_req>-e<err_info>s<status>-p<param>
Field identifier
Message field
Instance
type
id
src
dst
rsp_req
err_info
status
Variable, 2 to 640
param
Each field is optional and will cause the corresponding message field to be set to
zero if not present. All values are entered in hexadecimal.
For example,
M-tc701-i0000-f1d-d23-s00-p0000ffffffff
The following command file sends a reset circuit group message to the first ISUP
group, waits for 5 seconds and sends a reset group message for group 1.
*
* Example s7_play command file
*
M-tc701-i0000-f1d-d23-s00-p0000ffffffff
*
D-s0005
*
M-tc701-i0001-f1d-d23-s00-p0000ffffffff
Issue 5
Page 41
6.4 tim
Description:
The tim utility starts the tim process that receives periodic tick notification from tick
processes and handles protocol timers for all other processes.
The tim process is typically only started by forking a process using gctload.
Syntax:
tim_lnx [-v]
tim_nt [-v]
tim_sol [-v]
Command Line Options:
The tim utility supports the following command line option:
-v
Show version information.
Issue 5
Page 42
6.5 tick
Description:
The tick utility starts the tick process that sends periodic tick notification to the tim
process which in turn handles protocol timers.
The tick process is typically only started by forking a process using gctload.
Syntax:
tick_lnx [-v]
tick_nt [-v]
tick_sol [-v]
Command Line Options:
The tick utility supports the following command line option:
-v
Show version information.
Issue 5
Page 43
Mnemonic
Description
0x00
DVR_TASK_ID
0x10
MVD_TASK_ID
0x20
SSD_TASK_ID
0xb0
RSI_MOD_ID
0x21
CONG_TASK_ID
Congestion module
0x71
SS7_TASK_ID
0x22
MTP_TASK_ID
0x32
RMM_TASK_ID
0x23
ISP_TASK_ID
0x33
SCP_TASK_ID
0x14
TCP_TASK_ID
0x15
MAP_TASK_ID
0x25
IS41_TASK_ID
0x35
INAP_TASK_ID
0x4a
TUP_TASK_ID
0x0d
APP0_TASK_ID
0x1d
APP1_TASK_ID
0x2d
APP2_TASK_ID
0xdd
APP13_TASK_ID
0xed
APP14_TASK_ID
0xfd
APP15_TASK_ID
0x8e
MGMT_TASK_ID
0xdf
SIU_MGT_TASK_ID
0xef
REM_API_ID
0xff
Issue 5
Page 44
Issue 5
Page 45