(Page 1 of 1 in this chapter) Version

Chapter 3

Loader API

: 3.1 Loader API Specifics

3.1 Loader API Specifics

The loader API and structures can be found in the include file cplot.h. Applications that wish to use the loader API must link with the following files: cplot.lib
The following functions are called for each task load:

short Loader (LOADER_PARAMS *lp)

This function performs the download of a task. It returns 0 if successful or a non-zero error. The LOADER_PARAMS structure controls the loading and execution of the task.
/* Loader Control Structure */ typedef struct { short intno; /* Software interrupt to CPI [0x60-0x80] */ short cp; /* CP number [1-8] */ unsigned short dpbase; /* Dual port RAM base */ char *loadfile; /* Pointer to task/kernel load filename */ char *descrip; /* Pointer to 80 byte array for description */ short kernel; /* Kernel flag */ short destroy; /* Destroy flag */ short debug; /* Debug flag */ unsigned char cpkfunc; /* Special CPK Function flag */ char cpkfunctyp; /* Special CPK Function type */ char cpkmicro; /* CPK Microcode type <C6.50> */ unsigned char cpkq32cnt; /* No. of processors in QUICC32 mode */ char name[10]; /* Name of task */ unsigned long exopts; /* Task execution options */ short priority; /* Task priority */ unsigned long stack_size; /* Task stack size */ short autostart; /* Autostart flag */ TX_HANDLE cpi_handle; /* Handle to use talking to cpi lib */ } LOADER_PARAMS;
The fields of the LOADER_PARAMS structure are described in the following table. A u before the type indicates unsigned (uchar = unsigned char). Several of the fields exist only for backward DOS compatibility. These fields are unused in 32-bit operating systems and should be set to 0. Type Name Description short intno Interrupt number of the board. For backwards compatibility only. Set to 0. short cp Communications processor (board) number. Specifies which TX board to load the task on in multi-board systems. Valid values are 1 to 16. ushort dpbase Dual port RAM base address. For backwards compatibility only. Set to 0. char * loadfile Filename containing the binary image of the task. This is a pointer to a null-terminated string containing the filename. If the file to be loaded is not in the path variable, the filename must be fully qualified. Example: c:\nms\ss7\soft\cp\tpx.lot. char * descrip Pointer to a buffer where a description of the task, including version information, is returned after the task is loaded. It is a null-terminate string up to 80 characters long. This parameter can be set to NULL if no description is desired. Otherwise an 80 byte buffer must be allocated and passed here. short kernel Flag indicating whether the task being loaded is the kernel task. Set this value to 1 when loading the kernel task (cpknnnn.lot [TX 2000/TX 3000 only]). Set it to 0 for all other tasks. The kernel task is loaded differently from other tasks and must be the first task loaded. short destroy Flag indicating whether the task should be loaded or halted. Setting this flag to 0 loads the task; setting it to 1 halts a running task on the TX board. short debug Unused flag. Set to 0. uchar cpkfunc Flag used to indicate this file is not a task, but a special kernel configuration function. Set to 0 otherwise. char cpkfunctyp Indicates type of configuration functions. Currently only TDM configuration utility output is supported. Flag=t indicates this file is the output from the tdmcfg.exe utility. Set to 0 otherwise. char cpkmicro Microcode download flag. If set to 7, SS7 microcode is downloaded to the board. This flag is only valid when loading the kernel. Set to 0 otherwise. uchar cpkq32cnt Number of processors to put into QUICC32 mode. char[10] name Name of the task. Use the table in Chapter 2 to determine the name to use. Must be null terminated. ulong exopts Execution options. Internal flags used for debugging. Set to 0. short priority Priority the task will execute at. Allowed values are from 1 to 31, with 1 being the highest priority. System tasks use 1-5; user tasks (such as MTP and ISUP) should be set at 6 or greater, indicating lower priority. ulong stack_size The size of the stack used for task execution. Allowed values are from 4096 to 40960. The default is 4096 and should be sufficient for all tasks. short autostart Flag indicating that the task should be run as soon as it is loaded. In all but special debugging cases, this value should be set to 1. tx_handle cpi_handle Handle returned by the CPI Library. For DOS backwards compatibility only. Should be set to 0.

Type	Name	Description
`short`	`intno`	Interrupt number of the board. For backwards compatibility only. Set to 0.
`short`	`cp`	Communications processor (board) number. Specifies which TX board to load the task on in multi-board systems. Valid values are 1 to 16.
`ushort`	`dpbase`	Dual port RAM base address. For backwards compatibility only. Set to 0.
`char *`	`loadfile`	Filename containing the binary image of the task. This is a pointer to a null-terminated string containing the filename. If the file to be loaded is not in the path variable, the filename must be fully qualified. Example: c:\nms\ss7\soft\cp\tpx.lot.
`char *`	`descrip`	Pointer to a buffer where a description of the task, including version information, is returned after the task is loaded. It is a null-terminate string up to 80 characters long. This parameter can be set to NULL if no description is desired. Otherwise an 80 byte buffer must be allocated and passed here.
`short`	`kernel`	Flag indicating whether the task being loaded is the kernel task. Set this value to 1 when loading the kernel task (`cpknnnn.lot [TX 2000/TX 3000 only]`). Set it to 0 for all other tasks. The kernel task is loaded differently from other tasks and must be the first task loaded.
`short`	`destroy`	Flag indicating whether the task should be loaded or halted. Setting this flag to 0 loads the task; setting it to 1 halts a running task on the TX board.
`short`	`debug`	Unused flag. Set to 0.
`uchar`	`cpkfunc`	Flag used to indicate this file is not a task, but a special kernel configuration function. Set to 0 otherwise.
`char`	`cpkfunctyp`	Indicates type of configuration functions. Currently only TDM configuration utility output is supported. `Flag=t` indicates this file is the output from the `tdmcfg.exe` utility. Set to 0 otherwise.
`char`	`cpkmicro`	Microcode download flag. If set to 7, SS7 microcode is downloaded to the board. This flag is only valid when loading the kernel. Set to 0 otherwise.
`uchar`	`cpkq32cnt`	Number of processors to put into QUICC32 mode.
`char[10]`	`name`	Name of the task. Use the table in Chapter 2 to determine the name to use. Must be null terminated.
`ulong`	`exopts`	Execution options. Internal flags used for debugging. Set to 0.
`short`	`priority`	Priority the task will execute at. Allowed values are from 1 to 31, with 1 being the highest priority. System tasks use 1-5; user tasks (such as MTP and ISUP) should be set at 6 or greater, indicating lower priority.
`ulong`	`stack_size`	The size of the stack used for task execution. Allowed values are from 4096 to 40960. The default is 4096 and should be sufficient for all tasks.
`short`	`autostart`	Flag indicating that the task should be run as soon as it is loaded. In all but special debugging cases, this value should be set to 1.
`tx_handle`	`cpi_handle`	Handle returned by the CPI Library. For DOS backwards compatibility only. Should be set to 0.

(Page 1 of 1 in this chapter) Version

tech_support@nmss.com