ZCONFIG (3X)

NAME

zconfig - ZCOM Dynamic System Configuration (DSC)

SYNOPSIS

#include   <zcom/zcomsys.h>
#include   <zcom/zcomcall.h>     /* If compliled with ANSI C (recommended) */
 
int32 zconfig (zap, mode, node, cdata, rdata)
 
zaddr_type *zap;
uint32 mode;
uint32 node;
zconfig_type *cdata;
zcfgret_type *rdata; 

DESCRIPTION

Routine zconfig provides a general purpose mechanism for configuring a ZCOM system dynamically, i.e. altering some of the system tables or hardware settings while the system is running.

ATTENTION: The current release provides very limited user support for the functionality documented here. Specifically, the only supported functions are the Dynamic System Configuration (DSC) Control request to send a "Reconfiguration Complete" system event message and all of the Port Configuration actions.

The configuration modified by use of the zconfig routine is only effective while this instance of the ZCOM subsystem is running. The new configuration remains in force until changed by another call or until the ZCOM system is reinitialized. If the ZCOM subsystem is shutdown and restarted, the original configuration defined in the TTGEN configuration file is restored and all dynamic configuration changes are lost. Therefore, all permanent configuration information should be defined in the TTGEN configuration file.

This routine is intended for use by advanced user programs and should be used with care. Since this routine is used to dynamically modify the internal data structures used in the ZCOM subsystem, applications which use this functionality may need to be recompiled with new releases of the ACC base product.

The libraries libzcom_c.a and libpthread.a must be linked into the calling program by giving the options "-lzcom_c -lpthread" to cc(1) or ld(1)

Threads Considerations

This routine may be called from multi-threaded application using the POSIX (1003.1c) kernel threads API package. It has the following characteristics when called by multi-threaded application:

PARAMETERS

Configuration Data

The configuration data structure consists of a header and a "union" data portion for configuration information

/* Configuration Header */ 
typedef struct {
    uint16       config;        /* Type of configuration */
    uint16       action;        /* Configuration action */
    uint16       tag1;          /* Tag parameter 1 */
    uint16       tag2;          /* Tag parameter 2 */
 } zcfghdr_type;
 
/* Configuration Data */
 typedef struct {
     zcfghdr_type        header;      /* Header Information */
     union {
         struct {
             uint32      cfg_class;   /* Class of Reconfig (1-999 Resvd) */
             uint32      cfg_info1;   /* Caller supplied information. */
         } setctl;                    /* Request = DSC Control */
         struct {
             char        sysname[80]; /* New ZCOM system name */
             uint32      qlimit;      /* Queue limit */
         } setsys;
         struct {
             uint16      iftno;       /* Interface card number */
             uint8       bc1_addr;    /* 1st level bus converter addr */
             uint8       bc_addr;     /* Bus converter addr of hardware */
             uint16      card_addr;   /* Card address of new hardware */
             uint16      itype;       /* Interface card type */
             char        fname[ZCOM_MAXFNAME];  /* Firmware filename */ 
        } setcard;                   /* Request=Interface Configuration */
         struct {
             uint16      iftno;       /* Interface card number */
             uint8       bc1_addr;    /* 1st level bus converter addr */
             uint16      bc_addr;     /* Bus converter addr of hardware */
             uint16      card_addr;   /* Card address of new hardware */
             uint16      itype;       /* Interface card type */
             zcfg_lookup_t cfglt;     /* Configuration lookup table info */
             char        fname[ZCOM_MAXFNAME];  /* Firmware filename */
         } setcard_mmp;               /* Request=Interface Configuration */
                                      /* For Multi-msg BP protocol. */
         struct {
             uint16      iftno;       /* Interface card number */
             uint16      portno;      /* Port number */
             uint16      rcode;       /* Request code */
             uint16      spare;       /* Reserved, not used */
             zpconf_type cnfg;        /* Port configuration word */
             uint32      qlimit;      /* Port tx limit */
         } setport;                   /* Request = Port Configuration */
         struct {
             zaddr_type  zaddr;       /* Terminal ZLU */
             zaddr_type  daddr;       /* Destination terminal ZLU */
             uint16      iftno;       /* Interface card number */
             uint16      portno;      /* Port number */
             uint16      subchno;     /* Subchannel number */
             uint16      dtype;       /* Terminal device type */
             uint16      ltype;       /* Logical terminal type */
             zltt_type   ltt;         /* Logical terminal data */
             zptt_type   ptt;         /* Physical terminal data */
         } setterm;                   /* Request=Terminal Configuration */
         struct {
             uint16      iftno;       /* Interface card number */
             uint16      portno;      /* Port number */
             uint16      subchno;     /* 1/4 Subchannel number */
             uint16      rcode;       /* Request code */
             zptcfg_t    *ptcfg;      /* Ptr to port & subch config data */
             uint32      len;         /* Lgth (bytes) of ptcfg->ptinfo */
             unit32      qlimit;      /* Port transmit limit */
         } setportsc;                 /* Request = Port Sub-Chan Config. */
     } data;
 } zconfig_type;

The header specifies the configuration. It is returned without change in the response data, and may be used by the caller to identify a configuration request.

Field header.config specifies the type of configuration. The interpretation of the header.action and data fields vary depending on the configuration type. Allowed values are:

Field header.action specifies what action is to be taken for the specified configuration type. Its meaning depends on header.config.

Fields header.tag1 and header.tag2 are tag parameters and will be returned without change in the response data.

The union field data contains information for the configuration request. The relevant sub-field to be used depends on header.config.

Refer to the individual configuration sections for more information on configuration data.

Response Data

The response data structure consists of the header fields and a "union" data portion for completion response:

/* Configuration Response */
 typedef struct {
     zcfghdr_type        header;   /* Header Information */
     union {
         struct {
             int32       error;    /* Return ZCOM error */
         } ctlret;         struct {
             int32       error;    /* Return ZCOM error */
 
         } sysret;
         struct {
             uint32      iftno;    /* Interface card number */
             int32       error;    /* Return ZCOM error */
         } cardret;
         struct {
             uint32      iftno;    /* Interface card number */
             uint32      portno;   /* Port number */
             int32       status;   /* Return status */
         } portret;
         struct {
             zaddr_type  zaddr;    /* Terminal ZLU */
             int32       error;    /* Return ZCOM error */
         } termret;
         struct {
             uint32      iftno;    /* Interface card number */
             uint32      portno;   /* Port number */
             uint32      subchno;  /* Subchannel number */
             int32       status;   /* Return status */
         } portscret;
     } data;
 } zcfgret_type;

The header is the same as in the configuration data. Its fields are returned without change for the caller to identify the response.

The union field data contains response data returned from the specified configuration. The relevant sub-field to be used depends on header.config.

Refer to the individual configuration sections for more information on response data.

TYPES OF CONFIGURATION FUNCTION

DSC Control

The DSC control function is to provide global control and status on the access of DSC functions. There are 3 DSC control actions.

Action ZcENABLE_DSC(1) is to enable the DSC access after it has been disabled. By default, the DSC access is enabled when ZCOM system is started up.

Action ZcDISABLE_DSC(2) is to disable DSC access. When disabled, local processes attempting DSC functions will be suspended. For DSC requests from remote system, ZCOM error -41 (ZEDSCLOCK, DSC function is disabled) is returned.

Action ZcDSC_SEND_RECFG(3) is used to broadcast a "Reconfiguration Complete" system event message to all interested programs and protocol drivers. This action should only be used after completing all zconfig() calls to dynamically reconfigure the ZCOM subsystem. Any process or protocol driver which has previously called the ZCOM zevent_rcvr() routine will be notified with a system event message. A dynamic reconfiguration complete event message returns an event type of ZCOM_SETYPE_RECONFIG.

Configuration Data

header.config

header.action

header.tag1,
header.tag2

data.setctl.cfg_class

data.setctl.cfg_info1

Caller supplied information that should be specific to the type of reconfiguration which took place. In the case of ZcCLASS_X25, this field must contain the X.25 Level 2 ZLU of the link's configuration that was modified. Note that even if the ZLUs for a link were deleted from the configuration, the old Level 2 ZLU must still be supplied. A positive ZLU number indicates the link has been added, while a negative ZLU value indicates the link was deleted. This field is used for action 3 only.

Response Data

No specific response data or error.

System Configuration

There are 5 system configuration actions. They are for altering parameters related to the whole ZCOM runtime subsystem. Action 1 is for changing the ZCOM runtime system name. The system name is for information purposes only. This function does not affect the operation of the ZCOM subsystem.

Action 2-5 modify various default queue limits in the ZCOM subsystem. Such default limits only affect newly created queues. To modify limits on existing queues, use the zsetql(3X) routine instead.

Configuration Data

header.config

header.action

header.tag1,
header.tag2

data.setsys.sysname

data.setsys.qlimit

Response Data

data.sysret.error

The error message text may be fetched using zcomerror(3X) with a non-zero error code.

Interface Configuration

There are 6 interface configuration actions. They are used to alter the parameters related to an interface card, and for controlling the operation of an interface card.

Action ZcDSC_CHNG_FW_FILE (1) modifies the firmware file name (used to download the MUX card). This change will have no effect until the interface card is restarted, causing the new firmware file to be used to download the card.

Action ZcDSC_CREATE_IFT (2) allocates the internal data structures required for a new interface card. That is, it creates a new Interface Table entry.

Action ZcDSC_START_CARD (3) starts up an interface. This initializes the hardware, the ports and terminals according to the configuration kept in the ZCOM tables. In functionality, it is identical to a zmon restart command.

Action ZcDSC_HALT_CARD (4) halts the hardware and stops new requests to the ACC interface card. All pending buffers and terminals linked to the interface remain unchanged. This function prepares an Interface Table entry for reassignment to different hardware (a new MUX interface card).

Action ZcDSC_STOP_CARD (5) stops an interface card as in action ZcDSC_HALT_CARD. In addition, all buffers linked to the interface and its terminals are released. Terminals are then set to unavailable. This function may be used to prepares an interface for re-linking to different hardware, or to eliminate all pending resources for a failed card. It is identical to a zmon shutdown command.

Action ZcDSC_REASSIGN_IFT (6) associates an interface table entry with a different MUX interface card. An interface must be halted or stopped (i.e. action ZcDSC_HALT_CARD or ZcDSC_STOP_CARD) before this request can be issued.

Configuration Data

header.config

header.action

header.tag1,
header.tag2

data.setcard.iftno

data.setcard.bc1_addr

data.setcard.bc_addr

data.setcard.card_addr

data.setcard.itype

data.setcard.fname

Response Data

data.cardret.iftno

data.cardret.error

Port Configuration

There are 8 port configuration actions. Actions ZcDSC_ALL_PARMS, ZcDSC_CFG_MODE, ZcDSC_BAUD_RATE, and ZcDSC_PORT_MODE configure the datacomm ports on the MUX interface card. All terminal ZLUs on the port being changed must be disabled before the port configuration takes place (use zcntl to disable a terminal ZLU using request code ZCOM_MRQCODE_DSB[8]). Examine the TTGEN configuration file to determine which ports are defined for which MUX interface cards and the terminals associated with each port.

Action ZcDSC_BREAK_REQ is used to activate the Port Break Routine of the protocol firmware. Since Port configuration by-passes the normal terminal transmit queues, this function is used as a software interrupt to the protocol specific firmware to initiate a recovery process when there is a protocol problem and the transmit queues are "blocked up". If the protocol for the specified port does not support this facility, error status 8 is returned.

Action ZcDSC_SET_XMIT_LIMIT changes the port transmit limit of a specific port on a MUX card. This limit controls the flow of requests from the host to the card for terminals on the related port.

Action ZcDSC_ENABLE_PORT enables a port after it has been disabled (action ZcDSC_DISABLE_PORT).

Action ZcDSC_DISABLE_PORT disables a port putting it into an inoperative state. All linked terminals are marked without actually sending a disable request to the interface card. This is to avoid a "hung" terminal disable request due to a hardware failure on a port. This action is designed to isolate a port that has failed from the ZCOM system. The ZCOM system will stop using the port and the terminals on the failed port may then be moved or deleted.

Configuration Data

header.config

header.action

header.tag1,
header.tag2

data.setport.iftno

data.setport.portno

data.setport.rcode

data.setport.spare

data.setport.cnfg

data.setport.qlimit

Response Data

data.portret.iftno
data.portret.portno

data.portret.status

Port Subchannel Configuration

The port subchannel configuration is only valid for the E1/T1 interface. There are 12 port configuration actions. Actions ZcDSC_ALL_PARMS, ZcDSC_CFG_MODE, ZcDSC_BAUD_RATE, ZcDSC_PORT_MODE, ZcDSC_SET_TIMESLOTS and ZcDSC_SET_SUBC_SPECS configure the datacomm ports and/or subchannels on the MUX E1/T1 interface card. For actions other than ZcDSC_SET_TIMESLOTS and ZcDSC_SET_SUBC_SPECS all terminal ZLUs on the port being changed must be disabled before the port configuration takes place (use zcntl to disable a terminal using request code ZCOM_MRQCODE_DSB[8]). For actions ZcDSC_SET_TIMESLOTS and ZcDSC_SET_SUBC_SPECS all terminal ZLUs on the subchannel(s) being changed must be disabled before the port configuration takes place. Note that, if a timeslot is being reconfigured to a new subchannel both the old and new subchannels must have no enabled terminals, for the reconfiguration to proceed. Examine the TTGEN configuration file or use zinfo() to determine which ports/subchannels are defined for which MUX interface cards and the terminal ZLUs associated with each port.

Action ZcDSC_BREAK_REQ is used to activate the Port Break Routine of the protocol firmware. Since Port configuration by-passes the normal terminal transmit queues, this function is used as a software interrupt to the protocol specific firmware to initiate a recovery process when there is a protocol problem and the transmit queues are "blocked up". If the protocol for the specified port does not support this facility, error status PT_NO_BREAK (8) is returned.

Action ZcDSC_SET_XMIT_LIMIT changes the port transmit limit of a specific port on a MUX card. This limit controls the processing of transmit requests for terminals on the related port.

Action ZcDSC_ENABLE_PORT enables a port after it has been disabled (action ZcDSC_DISABLE_PORT).

Action ZcDSC_DISABLE_PORT disables a port putting it into an inoperative state. All linked terminals are marked disabled without actually sending a disable request to the interface card. This is to avoid a "hung" terminal disable request due to a hardware failure on a port. This action is designed to isolate a port that has failed from the ZCOM system. The ZCOM system will stop using the port and the terminals on the failed port may then be moved or deleted.

Action ZcDSC_ENABLE_SUBC enables a subchannel after it has been disabled (action ZcDSC_DISABLE_SUBC).

Action ZcDSC_DISABLE_SUBC disables a subchannel putting it into an inoperative state. All linked terminal ZLUs are marked disabled without actually sending a disable request to the interface card. This is to avoid a "hung" terminal disable request due to a hardware failure on a subchannel. This action is designed to isolate a subchannel that has failed from the ZCOM system. The ZCOM system will stop using the subchannel and the terminals on the failed subchannel may then be moved or deleted.

Action ZcDSC_SET_TIMESLOTS is used to modify timeslot assignments. Individual timeslots can be configured, without affecting the operation of the remaining timeslots on the same port.

Action ZcDSC_SET_SUBC_SPECS is used to modify subchannel specifications. Individual subchannels can be configured, without affecting the operation of the remaining subchannels on the same port.

Configuration Data

header.config

header.action

header.tag1,
header.tag2

data.setportsc.iftno

data.setportsc.portno

data.setportsc.subchno

data.setportsc.rcode

data.setportsc.ptcfg

data.setportsc.ptcfg->ptcnfg

data.setportsc.ptcfg->ptinfo.subchb.tmsl[ ]

data.setportsc.ptcfg->ptinfo.subchb.spec[ ]

data.setportsc.len

data.setportsc.qlimit

Response Data

data.portscret.iftno,
data.portscret.portno,
data.portscret.subchno

data.portscret.status

Terminal Configuration

There are 5 terminal configuration actions. They are for altering various internal linkages and terminal tables in the ZCOM runtime system memory.

Action ZcDSC_CREATE_LTT_PTT (1) creates a simple terminal that has one Logical Terminal Table (LTT) and one Physical Terminal Table (PTT).

	NOTE: For this new ZCOM terminal, zconfig() allocates data structures in the kernel for ZCOM drivers to access. However, related data structures for this terminal must also be allocated on the target ACC card to complete the task. To allocate the related firmware data structures, use zcntl() with the ZCOM_MRQCODE_TERM rcode value (see the zcntl(3X) man page).

Action ZcDSC_CREATE_LTT_ON_PTT (2) creates and links an LTT to an existing terminal. The newly created LTT becomes an inbound multiplexing terminal and bit ZCOM_LTFLAG_IMX of field "ltaddr" is set automatically.

Action ZcDSC_CLEAR_TERM (3) clears a terminal for deletion. It flushes data buffers and removes the receivers of a terminal. It is usually used to prepare a terminal for deletion. Note that a terminal must be disabled before it can be cleared.

Action ZcDSC_DELETE_TERM (4) removes a terminal and releases its table space to the free pool. If a terminal has multiple LTTs linked to it, only the LTT is removed, the PTT is untouched. Otherwise, both the LTT and PTT are removed. If the PTT is to be removed, it must be disabled and have no pending or active I/O requests. Action ZcDSC_CLEAR_TERM is designed to "clear" a terminal for deletion.

Action ZcDSC_MOVE_TERM (5) is to re-link a terminal to a different port, on the same or different interface cards. After moving the terminal entry, the terminal must be re-configured, enabled and activated (i.e. ZCNTL request 6, 7 and 9) before it can be re-used. A terminal must be disabled and have no active I/O requests before it can be moved.

Configuration Data

header.config

header.action

header.tag1,
header.tag2

data.setterm.zaddr

data.setterm.daddr

data.setterm.iftno

data.setterm.portno

data.setterm.subchno

data.setterm.dtype

data.setterm.ltype

data.setterm.ltt

data.setterm.ptt

Response Data

data.termret.zaddr

data.termret.error

NOTES

RETURN VALUE

zconfig returns 0 if the configuration request is accepted. A non-zero ZCOM error is returned if there is a problem with the request. See /opt/acc/include/zcom/zcomsys.h for the list of ZCOM error codes and their meanings.

For immediate configuration requests, a zero return indicates the request is complete and rdata should be checked for any configuration problem. A non-zero return value means the request is rejected and no valid data is returned in rdata.

EXAMPLE

#include     <zcom/zcomsys.h>
#include     <zcom/zcomcall.h>
 int32           ierr;
 zaddr_type      zaddr;
 uint32          node;
 zconfig_type    cdata;
 zcfgret_type    rdata;
 
cdata.header.config = ZCOM_ZCONFIG_PORT; cdata.header.action = ZcDSC_ALL_PARMS;
cdata.header.tag1   = 1; cdata.header.tag2   = 2; cdata.data.setport.iftno  = 0;
cdata.data.setport.portno = 4; cdata.data.setport.rcode  = 2;
cdata.data.setport.cnfg.pcval = 0x07178000;
 
if (ierr = \fBzconfig\fR (&zaddr, 0, node, &cdata, &rdata)) {      /* error return code */ } else {          /* good return code */ }

FILES

SEE ALSO

zsetql(3X), zcntl(3X).