HighWire-MTP2 Software Reference Rev. 1.2, September 4, 2002 Primary Text Number M8245 SBE, Inc. 2305 Camino Ramon, Suite 200, San Ramon, California 94583 (925) 355-2000 Technical Support (800) 444-0990 Fax: (925) 355-2020 FaxBack Service: (800) 214-4723 website: http://www.sbei.
Copyright ©2001, 2002 by Data Connection Limited, Inc. All rights reserved. Copyright ©2001, 2002 by SBE, Inc. All rights reserved. No part of this manual may be reproduced by any means without written permission from SBE, Inc., except that the purchaser may copy necessary portions for internal use only. While every effort has been made to ensure the accuracy of this manual, SBE cannot be held responsible for damage resulting from information herein. All specifications are subject to change without notice.
Contents 1. About This Manual ..................................................................................................................................... 9 1-1. Related Documents ..............................................................................................................................9 1-2. Documentation Conventions ................................................................................................................9 2. Software Installation and Removal .............
-3-7.CBI_MSG_AVAIL_CALLBACK ................................................................................................ 38 5. HW-MTP2 Level 2 - Level 3 Interfaces and Message Flows .................................................................39 5-1. Level 2 - Level 3 Management Interface .......................................................................................... 39 5-2. Level 2 - Level 3 Data Interface .................................................................................
6-3-21.CBI_M2_UNREGISTER ........................................................................................................ 76 6-3-22.CBI_M2_MSG_FOR_ XMISSION ........................................................................................................................................ 77 6-3-23.CBI_M2_OPEN .................................................................................................................... 78 6-3-24.CBI_M2_OUT_OF_SERVICE .......................................
Synopsis ........................................................................................................................................ 117 Return values ................................................................................................................................ 117 See also ......................................................................................................................................... 117 7-6. sbe_dprWrite ..............................................
9-1. CBI Function Return Codes ............................................................................................................. 137 9-2. CBI Return Codes ............................................................................................................................. 138 9-3. CBI_YES_NO ..................................................................................................................................... 138 9-4. CBI_MTP2_IPS_TYPES .....................................
Figures 3-1 3-2 5-1 5-2 5-3 5-4 5-5 5-6 5-7 5-8 5-9 HW-MTP2 Level2 - Level 3 interfaces..................................................................................................... 27 HighWire-MTP2 theory of operation........................................................................................................ 28 Message flows involved in registering with an L2 process and activating a link. ...............................
1. About This Manual This manual enables a third party to write applications making use of the MTP2 protocol executing on SBE’s HW400 board. The HighWire-MTP2 Software Reference manual covers the following topics: • Software installation • Cross Bus Interface • MTP Layer 2 - Layer 3 management interface • MTP Layer 2 - Layer 3 data interface 1-1.
About This Manual HighWire MTP-2 - 1.
2. Software Installation and Removal 2-1. Software Installation Software packages contained on the CDROM within the /cdrom/pkg directory reflect the Solaris operating system version with which the software is associated. • hw6mtp_ga_1_0.sbe • hw8mtp_ga_1_0.sbe • hw9mtp_ga_1_0.sbe hw9 reflects Solaris 9; hw8 reflects Solaris 8; hw6 reflects Solaris 2.6. The ga_X_X portion indicates that the package is an General Access product with a release level of 1.0.
2-2. Software Removal 1. Log in as root. You must have SuperUser privileges to install this package. 2. Issue the Package remove command: pkgrm SBEhw 3. Answer “Y” to the following prompt: The following package is currently installed: SBEhw SBE HighWire, Solaris 8 Driver w/MTP2 service Do you want to remove this package? 4.
2-3-1. Terminology Basic Hot Swap Hardware connection is automatic but the software connection and failover process is manual. Full Hot Swap Hardware connection is automatic, software connection is automatic, but the failover process is manual. HA Hot Swap Hardware connection is automatic, software connection is automatic, and the failover process is automatic as well. See the hardware-specific documentation of your Solaris system for details of its System Configuration Administration support. 2-3-2.
2-3-4. Daemon assignment The SBE HighWire family of products operates under control of a daemon that monitors status and controls access. The daemon is called wspd. There is a separate wspd daemon for each HighWire adapter in the system. The Process ID of the daemon associated with a particular board is available through the hwinfo command. Example: hwinfo -i 1 returns information about board 1. Below is a sample entry.
Certain systems may require manual termination of the board's controlling daemon. Locate the board's daemon process number (Control PID) using the HighWire hwinfo command (see the Daemon Assignment section, above). Then terminate the board's controlling daemon, using the hwcmd command. Example: hwcmd -r 1 Refer to your specific system's documentation for the correct procedure to unconfigure a board. You must have SuperUser privileges to unconfigure a board. 2-3-7.
## Installing part 1 of 1. /etc/opt/SBEhw/cfg/wsp.conf /etc/opt/SBEhw/cfg/wspcfgfile.hw400 /etc/opt/SBEhw/cfg/wspcmd.cfg /opt/SBEhw/bin/hw_daemon /opt/SBEhw/bin/hwcmd /opt/SBEhw/bin/hwinfo /opt/SBEhw/bin/hwstat /opt/SBEhw/bin/release.sh /opt/SBEhw/bin/wspcmd /opt/SBEhw/bin/wspd /opt/SBEhw/dev/devlink.tab.hw /opt/SBEhw/pdm/pdm.hw400 /opt/SBEhw/pdm/pdm.map400 /opt/SBEhw/pdm/pdm_hwmtp.hw400 /opt/SBEhw/pdm/pdm_hwmtp.
/opt/SBEhw/doc/sbe_BoardReady.htm /opt/SBEhw/doc/sbe_ctlClose.htm /opt/SBEhw/doc/sbe_ctlIssueMsg.htm /opt/SBEhw/doc/sbe_ctlOpen.htm /opt/SBEhw/doc/sbe_ctlRcvMsg.htm /opt/SBEhw/doc/sbe_dataOpen.htm /opt/SBEhw/doc/wsp.htm /opt/SBEhw/doc/wsp_conf.htm /opt/SBEhw/doc/wspcmd.htm /opt/SBEhw/doc/wspcmd_cfg.htm /opt/SBEhw/doc/wspd.htm /opt/SBEhw/lib/libcbi.so /opt/SBEhw/lib/libsbe.a /opt/SBEhw/lib/libsbe.so /opt/SBEhw/lib/sparcv9/libcbi.so /opt/SBEhw/lib/sparcv9/libsbe.a /opt/SBEhw/lib/sparcv9/libsbe.
/usr/share/man/man3x/sbe_BoardReady.3x /usr/share/man/man3x/sbe_ctlClose.3x /usr/share/man/man3x/sbe_ctlIssueMsg.3x /usr/share/man/man3x/sbe_ctlOpen.3x /usr/share/man/man3x/sbe_ctlRcvMsg.3x /usr/share/man/man3x/sbe_dataOpen.3x /usr/share/man/man4/wsp.conf.4 /usr/share/man/man4/wspcmd.cfg.4 /usr/share/man/man6/cbiDemo.6 /usr/share/man/man6/cbiptest.6 /usr/share/man/man6/dprDemo.6 /usr/share/man/man7d/wsp.7d /usr/share/man/sman3sbe/libdpr.3sbe /usr/share/man/sman3sbe/sbe_dprClose.
/opt/SBEhw/src/echo_demo/makecom /opt/SBEhw/src/echo_demo/sbeRelease.
2-3-8. Sample -pkgrm- command output # pkgrm SBEhw The following package is currently installed: SBEhw SBE HighWire, Solaris 8 Driver w/ MTP2 service. (sparcv9) REL: SOL8_HWMTP_GA_1_0 Do you want to remove this package? y ## Removing installed package instance This package contains scripts which will be executed with superuser permission during the process of removing this package. Do you want to continue with the removal of this package [y,n,?,q] y ## Verifying package dependencies.
/opt/SBEhw/lib/adb/commem_ctl /opt/SBEhw/lib/adb/board_queue /opt/SBEhw/lib/adb/bi_s /opt/SBEhw/lib/adb/bi_q_status_s /opt/SBEhw/lib/adb/alloc_page /opt/SBEhw/lib/adb/alloc_ctl /opt/SBEhw/lib/adb /opt/SBEhw/bin/wspb64 /opt/SBEhw/bin/wspb32 /opt/SBEhw/bin/doadb ## Removing pathnames in class /opt/SBEhw/src/echo_demo/sbeRelease.c /opt/SBEhw/src/echo_demo/makecom /opt/SBEhw/src/echo_demo/echoDemo.c /opt/SBEhw/src/echo_demo/Makefile /opt/SBEhw/src/echo_demo /opt/SBEhw/src/dpr_demo/sbeRelease.
/usr/share/man/sman3sbe/sbe_dprWrite.3sbe /usr/share/man/sman3sbe/sbe_dprRead.3sbe /usr/share/man/sman3sbe/sbe_dprPrint.3sbe /usr/share/man/sman3sbe/sbe_dprOpen.3sbe /usr/share/man/sman3sbe/sbe_dprIoctl.3sbe /usr/share/man/sman3sbe/sbe_dprHighwayReport.3sbe /usr/share/man/sman3sbe/sbe_dprConnectionReport.3sbe /usr/share/man/sman3sbe/sbe_dprConfigDefault.3sbe /usr/share/man/sman3sbe/sbe_dprClose.3sbe /usr/share/man/sman3sbe/libdpr.3sbe /usr/share/man/sman3sbe /usr/share/man/man7d/wsp.
/opt/SBEhw/src/include/sbe/dpr/dpr_driver.h /opt/SBEhw/src/include/sbe/dpr/connmgr.h /opt/SBEhw/src/include/sbe/dpr /opt/SBEhw/src/include/sbe/ctrld_if.h /opt/SBEhw/src/include/sbe/cbi/cbim2.h /opt/SBEhw/src/include/sbe/cbi/cbicssif.h /opt/SBEhw/src/include/sbe/cbi/cbi.h /opt/SBEhw/src/include/sbe/cbi /opt/SBEhw/src/include/sbe/bi_err.h /opt/SBEhw/src/include/sbe /opt/SBEhw/src/include /opt/SBEhw/src /opt/SBEhw/lib/sparcv9/libsbe.so /opt/SBEhw/lib/sparcv9/libsbe.a /opt/SBEhw/lib/sparcv9/libcbi.
/opt/SBEhw/bin/cbiDemo_32 /opt/SBEhw/bin/cbiDemo /opt/SBEhw /etc/rc2.d/S58hwd /etc/rc1.d/K50hwd /etc/rc0.d/K50hwd /etc/init.d/sbehwd /init.d/sbehwd ## Removing pathnames in class /usr/sbin/wspd /usr/sbin/wspcmd /usr/sbin/hwstat /usr/sbin/hwinfo /usr/sbin/hwcmd /usr/sbin/hw_daemon /usr/kernel/drv/wsp.conf /usr/kernel/drv/wsp /usr/kernel/drv/sparcv9/wsp /opt/SBEhw/pdm/pdm_hwmtp.map400 /opt/SBEhw/pdm/pdm_hwmtp.hw400 /opt/SBEhw/pdm/pdm.map400 /opt/SBEhw/pdm/pdm.
3. Introduction to HighWire-MTP2 3-1. HW400 Boards The HighWire family of communications boards includes the HW400c for host systems with CompactPCI interfaces and the HW400p for hosts with PCI interfaces. Note: The HighWire 400c/R, 400c/F, and 400p also have “Plus” versions: HW400c/R+, HW400c/F+, and HW400p+. The difference between the regular and Plus versions is in the Motorola processor. The regular versions use the Motorola MPC8240; the Plus versions use the faster 8245. 3-1-1.
HW400c/F. Base Board - An intelligent board that provides protocol and application processing on data communicated between the host and the network. Its primary components are the MPC8240 microprocessor, GlobeSpan/T.Sqware serial communication controller (SCC), and CSU/DSU functionality for eight T1/E1/J1 ports. Mezzanine Board (or daughter card) - The HW400c/F Mezzanine Board contains the CSU components and magnetics to manage space considerations, and also contains eight T1/E1/J1 ports.
3-2. HW-MTP2 Interface Overview The following external interfaces are present between MTP3 and HighWire MTP2 (HW-MTP2). • HW-MTP2 Level 2 - Level 3 Management Interface • HW-MTP2 Level 2 - Level 3 Data Interface These interfaces are illustrated in Figure 3-1. Figure 3-1 HW-MTP2 Level2 - Level 3 interfaces MTP3 level2level 3 management interface HW-MTP2 level2level 3 data interface MTP1 (E1/T1) The Level 2 - Level 3 Management and Data Interfaces are described in Chapters 5–8 of this manual.
3-3. Theory of Operation Figure 3-2 shows the interface between the host and application and the relationships of the software and hardware components. Figure 3-2 HighWire-MTP2 theory of operation MTP3 Solaris on SPARC CBI user space CBI library kernel space WSP driver cPCI bus VxWorks on HW400 SBE transport SRTI/target CBI MTP2 hardware The user communicates with the HW400 via the Cross Bus Interface (CBI) functions described in Chapter 4, Cross Bus Interface.
4. Cross Bus Interface The Cross Bus Interface (CBI) is a set of functions provided to an application which allows that application to exchange messages with one or more entities on each of one or more line cards. The design of this interface accomplishes three separate aims: • It provides a simple interface to the user. • It is easily portable to different platforms and different underlying transport mechanisms, subject to OS support for threads. • It is easily extendable to support new message types.
• Support for multiple MTP3 applications. • Support for multiple HW400 cards. 4-1-2. HWMTP2 for SDK For the purposes of this document, the system consists of two parts: • The CBI library, embedded into the hwmtp2_for_sdk.o executable, is a VxWorks-based counterpart to the CBI library for Solaris. It provides the same message-passing interface from the target system, without the use of STREAMS. • The MTP2 and MTP1 layers themselves, passing target-side messages to the HDLC controller. 4-2.
4-2-4. Connecting to and disconnecting from an MTP2 instance When an application wishes to communicate with an MTP2, it must first open a connection to the line card where the MTP2 will be located (as explained in Section 4-2-3). It must then open the MTP2 sub-interface (defined in the header file cbim2.h) by sending a CBI_M2_OPEN message. Once the application has received a CBI_M2_OPEN response, it may send one or more CBI_M2_REGISTER messages (one for each MTP2 with which it wishes to communicate).
component for the message (CBI_M2_MSG_FOR_XMISSION), then a data buffer must also be supplied. The data buffer is subject to the same constraints as the control buffer, except that the additional space must be provided both at the start and the tail of the data, and the amounts of empty space provided are determined by the send_data_hdr_size and send_data_tail_size fields of the CBI_M2_OPEN response. The MTP3 then invokes the cbi_send() API to dispatch the message.
This library-messaging mechanism allows the application (or layers above it) to impose flow control by allocating their buffers from a fixed size pool. When messages cannot be dispatched across the interface, the number of available buffers shrinks since the application may not free them back to the pool until they have been sent. When the pool contains no further available buffers, the application cannot send any more data.
4-3. Basic Interface Functions and API Calls 4-3-1. cbi_initialize Prototype. CBI_UINT32 cbi_initialize( CBI_SENT_CALLBACK * sent_cb, CBI_MSG_AVAIL_CALLBACK * msg_avail_cb) Description. This function is invoked by the user to initialize the library. It must be invoked before any other calls are made. Parameters sent_cb This callback has been deprecated [null] for Highwire MTP2 for Solaris GA 1.0. This value is null for HWMTP2 for SDK, since all messages are guaranteed to be delivered to the stack.
4-3-2. cbi_terminate Prototype. void cbi_terminate(void) Description. This function is invoked by the user to terminate the library. It must be invoked when the application does not wish to make any further calls across the interface. Parameters. None. Returns. void. 4-3-3. cbi_open Prototype. CBI_UINT32 cbi_open( const char *name, CBI_CORR * cbi_correlator, CBI_CORR appl_correlator) Description. This function is invoked by MTP3 to obtain a correlator for subsequent communications to a line card.
4-3-4. cbi_close Prototype. CBI_UINT32 cbi_close( CBI_CORR cbi_correlator) Description. This function is used to signal the driver that no further messages will be transferred in either direction to the line card which is identified by the cbi_correlator. Parameters. cbi_correlator The correlator returned by the cbi_open() call. Returns. CBI_RC_SYNC_COMPLETE if the driver has successfully processed the cbi_close(). Otherwise, a specific error code. 4-3-5. cbi_recv Prototype.
Returns. • CBI_RC_SYNC_COMPLETE if a message was successfully obtained. • CBI_RC_ASYNC_COMPLETE if only part of a message was available. In this case, the buffers returned to the application contain only a partial message and should not be used. The next time the library signals that another message is available, the same buffers should be passed back to the library and the remainder of the message will be filled in. • CBI_RC_NO_MSG if no message was available for the user (i.e.
4-3-7. CBI_MSG_AVAIL_CALLBACK Prototype. typedef int CBI_MSG_AVAIL_CALLBACK( CBI_CORR appl_correlator, CBI_LONG ips_type, CBI_BUF_SIZE ctrl_len, CBI_BUF_SIZE data_len) Description. This routine informs the user application that a message is available to be received. The user should immediately issue a cbi_recv() to receive the message.
5. HW-MTP2 Level 2 - Level 3 Interfaces and Message Flows 5-1. Level 2 - Level 3 Management Interface The Level 2 - Level 3 Management Interface allows an L3 component to manage the operation of an L2 component.
• CBI_M2_QUERY_STATS • CBI_M2_QUERY_STATUS • CBI_M2_RB_CLEARED • CBI_M2_REM_PROCSSR_OUTAGE • CBI_M2_REM_PROCSSR_RECOVRD • CBI_M2_RETRIEVAL_COMPLETE • CBI_M2_RETRIEVAL_NOT_POSS • CBI_M2_RETRIEVED_MESSAGE • CBI_M2_RETRIEVE_BSNT • CBI_M2_RTB_CLEARED • CBI_M2_START • CBI_M2_STOP • CBI_M2_UNAVAILABLE • CBI_M2_UPDATE_PARMS These structures are defined in the header file cbim2.h and described in more detail in Chapter 6, CBI Buffer Formats. 5-2.
5-3. Message Flows The L3 uses the Level 2 - Level 3 Interfaces to register with as many instances of L2 as it requires, to activate and deactivate links, to access and respond to status information, and to send and receive data. This section describes typical flows that the L3 can use. This section is not intended to be a full set of signal flows; other flows of signals are possible, and some signals are not included. The signal structures are described in detail in Chapter 6, CBI Buffer Formats.
5-3-1. Link activation Figure 5-1 Message flows involved in registering with an L2 process and activating a link. L3 L2 CBI_M2_REGISTER (1) CBI_M2_REGISTER (rsp) CBI_M2_AVAILABLE (2) CBI_M2_UPDATE_PARMS (3) CBI_M2_UPDATE_PARMS (rsp) CBI_M2_EMERGENCY (4) CBI_M2_START (5) CBI_M2_IN_SERVICE (6) Data Transmission 1. L3 sends a CBI_M2_REGISTER to L2 to identify the correct MTP3 process with which L2 should communicate.
5-3-2. Remote Processor Outage (RPO) RPO with ITU-T national option LPO to RPO latching. Figure 5-2 Message flows involved when the remote end of the link suffers a processor outage. L3 L2 CBI_M2_REM_PROCSSR_OUTAGE (1) CBI_M2_LOC_PROCSSR_OUTAGE (2) . . . CBI_M2_LOC_PROCSSR_RECOVRD (3) . . . CBI_M2_REM_PROCSSR_RECOVRD (4) 1. L2 issues a CBI_M2_REM_PROCSSR_OUTAGE to L3 to indicate that the remote end of the link is signalling a processor outage condition. 2.
RPO with ITU-T or ANSI changeover in progress on recovery. Figure 5-3 Message flows involved when the remote end of the link suffers a processor outage. L3 L2 CBI_M2_REM_PROCSSR_OUTAGE (1) CBI_M2_REM_PROCSSR_RECOVRD (2) CBI_M2_CONTINUE (3) 1. L2 issues a CBI_M2_REM_PROCSSR_OUTAGE to L3 to indicate that the remote end of the link is signalling a processor outage condition. 2.
RPO with ANSI changeover complete on recovery. Figure 5-5 Message flows involved when the remote end of the link suffers a processor outage. L3 L2 CBI_M2_REM_PROCSSR_OUTAGE (1) CBI_M2_REM_PROCSSR_RECOVRD (2) CBI_M2_FLUSH BUFFERS (3) CBI_M2_RTB_CLEARED (4) CBI_M2_RB_CLEARED (5) 1. L2 issues a CBI_M2_REM_PROCSSR_OUTAGE to L3 to indicate that the remote end of the link is signalling a processor outage condition. 2.
5-3-3. Changeover following local detection of link failure Figure 5-6 Message flows involved when L2 detects that a link has failed. L3 L2 CBI_M2_OUT_OF_SERVICE (1) CBI_M2_RETRIEVE_BSNT (2) CBI_M2_BSNT CBI_M2_RETRIEVAL_REQ_FSNC (3) CBI_M2_RETRIEVED_MESSAGE CBI_M2_RETRIEVED_MESSAGE . . . CBI_M2_RETRIEVAL_COMPLETE (4) 1. When L2 detects that the link has become unusable, it sends a CBI_M2_OUT_OF_SERVICE signal to inform L3. 2.
5-3-4. Failover of MTP3 Control Part Figure 5-7 Message flows involved after failover of the control part of MTP3 has occurred. L3 L2 CBI_M2_REGISTER (1) CBI_M2_REGISTER (rsp) CBI_M2_AVAILABLE CBI_M2_QUERY_STATUS (2) CBI_M2_QUERY_STATUS (rsp) CBI_M2_STOP (3) 1. L3 sends a CBI_M2_REGISTER to L2 to identify the new MTP3 process with which L2 should communicate. L2 returns the signal as a response indicating whether the registration was successful.
5-3-5. MTP3 Data Part failure Figure 5-8 Message flows involved when the data part of MTP3 fails and is immediately replaced. L3 L2 CBI_M2_REGISTER (1) CBI_M2_REGISTER (rsp) (2) CBI_M2_LOC_PROCSSR_RECOVRD (3) When L2 is informed of the failure of the MTP3 Data Part, it behaves as if it had received a Local Processor Outage signal from MTP3. 1. When L2 is informed of the replacement MTP3 Data Part, it sends a CBI_M2_REGISTER to L3 to register with the new MTP3 data process. 2.
6. CBI Buffer Formats The header files cbi.h and cbim2.h contains all the structures that define the format of information within the control buffers passed between the user application and the library in the ctrl_buffer parameter of the cbi_send and cbi_recv calls. Note that both control and data buffers consist of contiguous memory, and that control buffers of messages which possess data parts contain fields indicating the offset of the start of any data within its buffer and the length of the data. 6-1.
num_cong_levels The number of levels (other than zero) used for transmission congestion control. If cong_method is CBI_CONG_CTRL_NATL_WITH_PRI or CBI_CONG_CTRL_NATL_BUFFER, this field denotes how many entries are valid in the cong_onset, cong_onset cong_abate, and possibly cong_discard arrays. The comments on those fields assume a value of 3, for clarity. If cong_method is CBI_CONG_CTRL_NATL_TIMER, this field denotes the number of congestion states allowed.
initial_status The initial value assigned to the transmission congestion state when the current congestion level is 0 and the number of queued messages first exceeds the congestion onset threshold. This value must be less than the value of num_cong_levels. num_cong_levels Note that the timer Tx is not used in this instance. rcv_pool_capacity The capacity of the buffer pool used to receive messages from the partner level 2. Transmission congestion onset and abatement thresholds.
Transmission congestion discard thresholds. The array index 0 is always valid. It is the absolute discard threshold. When the number of messages queued in L2's transmit and retransmit queues exceeds the absolute discard threshold, L2 always discards all new messages from L3, irrespective of the value of cong_method.
CBI_ULONG eim_te; CBI_ULONG eim_t8; CBI_ULONG eim_ue; CBI_ULONG eim_de; } CBI_M2_MTP2_EIM_PARMS; typedef struct cbi_m2_mtp2_link_parms { CBI_LONG error_correction_method; CBI_ULONG transmission_rate; CBI_ULONG loop_delay; CBI_ULONG sequence_num_bits; CBI_ULONG send_msu_window; CBI_ULONG send_octet_window; CBI_ULONG rcv_msu_window; } CBI_M2_MTP2_LINK_PARMS; typedef struct cbi_m2_mtp2_rcv_cong_parms { CBI_ULONG onset; CBI_ULONG abate; } CBI_M2_MTP2_RCV_CONG_PARMS; typedef struct cbi_m2_mtp2_suerm_parms { CBI_
timers.t_t2_dur t_t2_dur Q.703 T2 timer. Total time, in milliseconds, that the L2 attempts link alignment. If the link has still not aligned by this time, the link activation is failed. timers.t_t3_dur t_t3_dur Q.703 T3 timer. Total time, in milliseconds, that the L2 remains aligned before starting proving while waiting for the remote L2 to also become aligned. If the remote L2 does not become aligned by this time, the link activation is failed. timers.t_t4n_dur t_t4n_dur Q.703 T4 timer for normal proving.
link_parms MTP2 link parameters. link_parms.error_correction_method error_correction_method Specifies the error correction method to be used. This field can take the following values: • CBI_ERR_METHOD_BASIC • CBI_ERR_METHOD_PCR link_parms.transmission_rate transmission_rate Specifies the transmission rate of the link (in bits/second) and implies the transmission type (56 and 64 kbits, or faster imply digital; 4.8 kbits implies analog). Note that CBI_XMIT_RATE_MBITS1_5 is used to denote 1.
aerm Alignment Error Rate Monitor (AERM) parameters (used during proving). aerm.aerm_tin aerm_tin Q703 AERM Tin parameter. Normal-mode threshold of the (AERM) counter. aerm.aerm_tie aerm_tie Q703 AERM Tie parameter. Emergency-mode threshold of the (AERM) counter. aerm.aerm_n aerm_n Q703 AERM N parameter. The number of octets that causes an increment of the AERM counter while in “octet counting” mode. in_service_monitor Type of monitor to use while in the In Service state.
eim.eim_ue eim_ue Q703 EIM UE parameter. Increment of the EIM counter after each interval in which an error occurred eim.eim_de eim_de Q703 EIM DE parameter. Decrement of the EIM counter after each interval in which no error occurred. 6-1-3. CBI_M2_SAAL_PARMS This structure is not used in MTP2 implementations and should be zeroed. 6-1-4. CBI_PKT_HDR This structure is a header for all messages which include control and data parts. Data structure.
CBI_M2_QUERY_STATS CBI_M2_QUERY_STATUS CBI_M2_EV_REGISTER CBI_M2_EV_UNREGISTER Retrieves processing status information from L2. Directs L2 to send event notifications. Directs L2 to stop sending notifications. CBI_M2_LOC_PROCSSR_ OUTAGE Notifies L2 that the L3 component has experienced a processor outage. CBI_M2_LOC_PROCSSR_ RECOVRD Notifies L2 that the L3 component has recovered from a processor outage.
6-2-2. Signals sent from L2 to L3 The following signals are sent from L2 to the L3. Note that some of these signals are event indications, and are only sent if the L3 has registered for receipt of them with the CBI_M2_EV_REGISTER request. CBI_M2_AVAILABLE Notifies the L3 that L2 initialization is complete and that the L2 is available to send messages. CBI_M2_UNAVAILABLE Notifies the L3 that the L2 is now unavailable to send messages.
CBI_M2_REM_ PROCSSR_OUTAGE Notifies the L3 that the remote end of the link is signaling a processor outage condition. CBI_M2_REM_ PROCSSR_RECOVRD Notifies the L3 that the remote end of the link has signaled that a processor outage condition has ended. CBI_M2_RB_CLEARED 60 CBI Buffer Formats Notifies the L3 that the receive buffer has been cleared, as requested by the L3. ANSI only. CBI_M2_RTB_CLEARED Notifies the L3 that the retransmission buffer has been cleared, as requested by the L3. ANSI only.
6-3. CBI Messages: Detailed Description Note: The CBI messages are listed in alphabetical order. 6-3-1. CBI_M2_AVAILABLE L2 sends this signal to the L3 at some point after responding to a CBI_M2_REGISTER to notify the L3 that the L2 has completed the join to the L2-L3 Data Interface and is available to receive further signals. Until the L3 has received this signal, the only signal that it may send to the L2 is a CBI_M2_UNREGISTER. There is no response to this message. Data structure.
6-3-3. CBI_M2_BSNT_NOT_RETRIE VABL L2 sends this message to the L3 in response to a CBI_M2_RETRIEVE_BSNT request if it cannot retrieve the sequence number of the last received message. There is no response to this message. Data structure. typedef struct cbi_m2_bsnt_not_retrievabl { CBI_IPS ips_hdr; } CBI_M2_BSNT_NOT_RETRIEVABL; Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_BSNT_NOT_RETRIEVABL.
6-3-5. CBI_M2_CLOSE L3 sends this message to L2 at the end of all processing to close a connection to a line card. It should be issued before the calls cbi_close() and cbi_terminate(). Data structure. typedef struct cbi_m2_close { CBI_IPS ips_hdr; } CBI_M2_CLOSE; Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_CLOSE sender_handle - not valid receiver_handle - not valid 6-3-6.
6-3-7. CBI_M2_CREDIT L3 sends this message to L2 to inform L2 that L3 has completed processing a number of received messages. This message allows L2 to release buffers back to the MTP2 buffer pool and acts as receive-side flow control. L3 must ensure that it sends the CBI_M2_CREDIT message to L2 with sufficient frequency to avoid emptying the MTP2 buffer pool.
6-3-8. CBI_M2_CREDIT_ERROR This message is sent by L2 to L3 to inform the application that it has sent an invalid credit message. Note: This message is not intended for normal operation. It is intended to be used as an aid to L3 development/integration in that it will be sent to the L3 when the L3 has attempted to grant credit for messages it has not received. If the L2 receives an invalid CBI_M2_CREDIT message (num_msgs is too large), it will send a CBI_M2_CREDIT_ERROR message back to the L3.
6-3-10. CBI_M2_EMERGENCY_ CEASES The L3 sends this message to L2 to request that it return to normal link proving. This process involves exchanging the full set of data proving signals with the peer L2 process. There is no response to this signal. Data structure. typedef struct cbi_m2_emergency_ceases { CBI_IPS ips_hdr; } CBI_M2_EMERGENCY_CEASES; Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_EMERGENCY_CEASES.
type The type of the event indication; one of the following values: CBI_M2_EV_LINK_STATUS CBI_M2_EV_SL_FAIL_ALL CBI_M2_EV_SL_FAIL_FIBR _BSNR Changes in link status. Link failure - all reasons. Link failure - abnormal FIBR/BSNR. CBI_M2_EV_SL_FAIL_ NO_RSP Link failure because the partner L2 process failed to respond within the required time. CBI_M2_EV_SL_FAIL_ ERROR_RATE Link failure because the Error Monitor has failed the link.
proving_mode The proving mode in use by L2. This field is only valid if the type field has the value CBI_M2_EV_LINK_STATUS and the status field has the value CBI_M2_LINK_PROVING, CBI_M2_LINK_ALIGNED, or CBI_M2_LINK_IN_SERVICE. This field can take the following values: 6-3-12. CBI_M2_EV_REGISTER CBI_M2_PS_PROVING_ UNKNOWN L2 has not yet started link proving. CBI_M2_PS_PROVING_ NORMAL L2 is performing Normal link proving. CBI_M2_PS_PROVING_ EMERGENCY L2 is performing Emergency link proving.
event_code Flags for the events for which L3 is requesting notification. This field can take a combination of the values, combined using a bitwise OR. Values for indication types are: CBI_M2_EV_LINK_STATUS CBI_M2_EV_SL_FAIL_ALL CBI_M2_EV_SL_FAIL_FIBR _BSNR Changes in link status. Link failure - all reasons. Link failure - abnormal FIBR/BSNR. CBI_M2_EV_SL_FAIL_ NO_RSP Link failure because the partner L2 process failed to respond within the required time.
6-3-13. CBI_M2_EV_UNREGISTER L3 sends this signal to L2 to unregister previous registrations for event notification. L2 returns the signal as a response. Data structure. typedef struct cbi_m2_ev_unregister { CBI_IPS ips_hdr; CBI_ULONG event_code; } CBI_M2_EV_UNREGISTER; Parameters on request. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_EV_UNREGISTER. sender_handle - L3’s handle for the join for this link.
Parameters on response. ips_hdr IPS Header. For definition, see Section 6-1-1. Handles from request are swapped. 6-3-14. CBI_M2_FLUSH_BUFFERS The L3 sends this message to L2 following a processor outage to request that it discard any data messages pending transmission before the processor outage occurred, and resume sending data messages to its peer L2 process. This message is referred to as “clear buffers” in the ANSI version of the MTP2 spec.
6-3-15. CBI_M2_IN_SERVICE L2 sends this message to the L3 when the link proving phase has completed successfully. The L3 may now transmit data packets. There is no response to this message. Data structure. typedef struct cbi_m2_in_service { CBI_IPS ips_hdr; } CBI_M2_IN_SERVICE; Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_IN_SERVICE. sender_handle - L2’s handle for the join for this link.
cong_level This is the current congestion level when multiple congestion levels have been configured. Constants for the congestion level in use by L2. This field can take the following values: • CBI_M2_CONG_LEVEL_1 • CBI_M2_CONG_LEVEL_2 • CBI_M2_CONG_LEVEL_3 • CBI_M2_CONG_NONE 6-3-17. CBI_M2_LINK_CONGSTN_ CEASED L2 sends this message to the L3 when a congestion condition in the lower layers (previously reported with the CBI_M2_LINK_CONGESTED signal) is cleared.
6-3-19. CBI_M2_LOC_PROCSSR_ RECOVRD The L3 sends this signal to L2 to notify L2 that the L3 process has recovered from a processor outage. There is no response to this signal. Data structure. typedef struct cbi_m2_loc_procssr_recovrd { CBI_IPS ips_hdr; } CBI_M2_LOC_PROCSSR_RECOVRD; Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_LOC_PROCSSR_RECOVRD. sender_handle - L3’s handle for the join for this link.
Parameters on request. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_REGISTER. sender_handle - L3’s handle for the join for this link. receiver_handle - L2’s handle for the join for this link. l3_mgmt_pid Process ID to which L2 must send all management messages for this L3, including the CBI_M2_REGISTER response. l3_mgmt_qid Queue ID to which L2 must send all management messages for this L3, including the CBI_M2_REGISTER response.
Parameters on response. ips_hdr IPS Header. For definition, see Section 6-1-1. Handles from request are swapped. return_code Return code from L2 to L3 indicating whether the L2 stack initialized successfully. This field can take the following values: CBI_OK CBI_UNSUCCESSFUL 6-3-21. CBI_M2_UNREGISTER The stack was initialized successfully. The stack was not initialized. The L3 sends this signal to L2 to dissociate the L3 from the L2 process.
6-3-22. CBI_M2_MSG_FOR_ XMISSION The L3 sends this message to the L2 to pass it a data message to be sent over the link. There is no response to this message. Data structure. typedef struct cbi_m2_msg_for_xmission { CBI_IPS ips_hdr; CBI_PKT_HDR pkt_hdr; CBI_ULONG dest_pt_code_len; CBI_BYTE dest_pt_code[CBI_MAX_DEST_PT_CODE_LEN]; } CBI_M2_MSG_FOR_XMISSION; Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_MSG_FOR_XMISSION.
6-3-23. CBI_M2_OPEN L3 sends this message to L2 during initialization, immediately after issuing the cbi_open() call. It opens a connection to the line card. L2 returns the signal as a response. Data structure.
l1_line_type [CBI_L1_MAX_FRAMERS] The physical line type for each framer on the line card. The types are: CBI_HM_DS1LF_D4 - T1/D4 CBI_HM_DS1LF_D4_MF - T1/MultiFrame CBI_HM_DS1LF_ESF - T1 extended Super Frame CBI_HM_DS1LF_ESF_MF CBI_HM_DS1LF_E1 - E1/no CRC CBI_HM_DS1LF_E1_CRC- E1/CRC CBI_HM_DS1LF_E1_MF - E1/MultiFrame CBI_HM_DS1LF_E1_CRC_MF - E1/MultiFrame, CRC4 l1_line_code [CBI_L1_MAX_FRAMERS] The physical line code for each framer on the line card.
send_data_tail_size On response, this field contains the size of additional free space at the end of all data packets that the application passes to the CBI library. Return code. On response, this field indicates whether the open was successfully processed. The following values are allowed: CBI_OK CBI_UNSUCCESSFUL 6-3-24. CBI_M2_OUT_OF_SERVICE The open message succeeded. The open message did not succeed.
6-3-25. CBI_M2_QUERY_CONFIG The L3 sends this signal to L2 to request configuration information. L2 returns the signal as a response. Data structure. typedef struct cbi_m2_query_config { CBI_IPS ips_hdr; CBI_ULONG return_code; CBI_M2_COMMON_PARMS common; CBI_M2_MTP2_PARMS mtp2; CBI_M2_SAAL_PARMS saal; } CBI_M2_QUERY_CONFIG; Parameters on request. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_QUERY_CONFIG.
6-3-26. CBI_M2_QUERY_STATS The L3 sends this signal to L2 to request the return of statistical information. L2 returns the signal as a response. Data structure. typedef struct cbi_m2_query_stats { CBI_IPS ips_hdr; CBI_HANDLE correlator; CBI_ULONG return_code; CBI_BYTE reset_stats; CBI_M2_COMMON_STATS common; CBI_M2_MTP2_STATS mtp2; CBI_M2_SAAL_STATS saal; } CBI_M2_QUERY_STATS; Substructures.
Parameters on request. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_QUERY_STATS. sender_handle - L3’s handle for the join for this link. receiver_handle - L2’s handle for the join for this link. correlator Correlator field is supplied on the request and returned on the response. reset_stats Indicates if and how L2 should reset any of the statistics to zero.
common common.duration_in_service duration_in_service The length of time that the status of the link has been CBI_M2_LINK_IN_SERVICE. This parameter is a cumulative count; it applies to the total length of time that the link has been active since the counter was last reset. common.num_align_failures num_align_failures The total number of link alignment failures. common.num_retrans_rqs_sent num_retrans_rqs_sent The number of sequenced data messages for which L2 had to request retransmission. common.
If the National option of multiple congestion discard levels is configured, then the number of messages discarded for levels 1–3 are stored in array indexes 1–3. common.num_cong_with_discard num_cong_with_discard The total number of congestion events (for each congestion level) which resulted in one or more messages being discarded.
6-3-27. CBI_M2_QUERY_STATUS The L3 sends this signal to L2 to request link status information. L2 sends this signal in response. Data structure. typedef struct cbi_m2_query_status { CBI_IPS ips_hdr; CBI_BYTE cong_level; CBI_BYTE link_status; CBI_BYTE ups; CBI_BYTE lpo; CBI_BYTE retrieval_pending; CBI_BYTE link_avail_status; CBI_BYTE update_parms_pending; CBI_ULONG event_code; CBI_M2_MTP2_STATUS mtp2; } CBI_M2_QUERY_STATUS; Substructure.
cong_level The current congestion level. For single congestion thresholds, 0 means Not Congested, and 1 means Congested. For multiple congestion levels, this field can take values 0 - num_cong_levels (from M2_UPDATE_PARMS) inclusive. Constants for the congestion level in use by L2. This field can take the following values: • CBI_M2_CONG_LEVEL_1 • CBI_M2_CONG_LEVEL_2 • CBI_M2_CONG_LEVEL_3 • CBI_M2_CONG_NONE link_status The link status.
link_avail_status The availability status. This field can take the following values: CBI_M2_AVAIL_ UNDEFINED CBI_M2_AVAILABLE CBI_M2_UNAVAILABLE The L2 has not sent a CBI_M2_AVAILABLE or a CBI_M2_UNAVAILABLE signal to the L3 yet. The L2 has sent a CBI_M2_AVAILABLE to the L3, and has never sent a CBI_M2_UNAVAILABLE. The L2 has sent a CBI_M2_UNAVAILABLE signal to the L3. update_parms_pending Update parameters SET or CANCEL pending.
mtp2 MTP2-specific status fields, as follows: mtp2.rpo rpo This indicates the status of a Remote Processor Outage. This field can take the following values: • CBI_M2_RPO_RECOVERED • CBI_M2_RPO_OUTAGE • CBI_M2_RPO_PENDING_CONTINUE mtp2.continue_pending continue_pending Continue status. This indicates whether L2 is currently awaiting a CBI_M2_CONTINUE, CBI_M2_FLUSH_BUFFERS, or CBI_M2_CLEAR_RTB request from the L3, following the end of a local or remote processor outage condition.
Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_RB_CLEARED. sender_handle - L2’s handle for the join for this link. receiver_handle - L3’s handle for the join for this link. 6-3-29. CBI_M2_RECEIVED_ MESSAGE The L2 sends this message to the L3 to pass it a data message received from the partner L2 process. There is no response to this message.
6-3-30. CBI_M2_REM_PROCSSR_ OUTAGE L2 sends this message to the L3 to indicate that the remote end of the link is transmitting status signal units indicating processor outage. There is no response to this message. Data structure. typedef struct cbi_m2_rem_procssr_outage { CBI_IPS ips_hdr; } CBI_M2_REM_PROCSSR_OUTAGE; Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_REM_PROCSSR_OUTAGE.
6-3-32. CBI_M2_RETRIEVAL_ COMPLETE L2 sends this message to the L3 once all data messages have been returned in response to a CBI_M2_RETRIEVAL_REQ_FSNC message. This includes the case when there are no data messages to return. There is no response to this message. Data structure. typedef struct cbi_m2_retrieval_complete { CBI_IPS ips_hdr; } CBI_M2_RETRIEVAL_COMPLETE; Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1.
6-3-34. CBI_M2_RETRIEVAL_REQ_ FSNC The L3 sends this message to the L2 to request that it return data messages that were previously sent by the L3 for transmission by the L2, but which have not yet been acknowledged by the peer L2 process. The messages to be returned are those starting from the one after the given sequence number. The L2 returns the messages using CBI_M2_RETRIEVED_MESSAGE messages on the L2 - L3 Management Interface. Data structure.
6-3-36. CBI_M2_RETRIEVE_BSNT The L3 sends this message to L2 to request that it process all data messages received so far, and then send a CBI_M2_BSNT signal back to the L3 to inform it of the sequence number of the last received message. In the case where the sequence number cannot be obtained, the L2 sends back a CBI_M2_BSNT_NOT_RETRIEVABL message. Data structure. typedef struct cbi_m2_retrieve_bsnt { CBI_IPS ips_hdr; } CBI_M2_RETRIEVE_BSNT; Parameters. ips_hdr IPS Header.
6-3-38. CBI_M2_START The L3 sends this message to L2 to request that it start alignment procedures with its peer L2 process. There is no direct response to this message, but if the alignment procedures succeed, L2 sends a CBI_M2_IN_SERVICE message to the L3. Data structure. typedef struct cbi_m2_start { CBI_IPS ips_hdr; } CBI_M2_START; Parameters. ips_hdr IPS Header. For definition, see Section 6-1-1. The following fields are specified below: ips_type - IPS_CBI_M2_START.
6-3-40. CBI_M2_UNAVAILABLE An L2 sends this signal to the L3 to notify it that the join to the L2-L3 Data Interface has permanently failed, and the L2 is unable to support the link. When the L3 receives this message, it unjoins with the L2. This signal may be sent instead of a CBI_M2_AVAILABLE signal (as the next signal after responding to a CBI_M2_REGISTER request), if the L2 is unable to join to the L2-L3 Data Interface. There is no response to this message. Data structure.
Data structure. typedef struct cbi_m2_update_parms { CBI_IPS ips_hdr; CBI_ULONG return_code; CBI_BYTE update_type; CBI_M2_COMMON_PARMS common; CBI_M2_MTP2_PARMS mtp2; CBI_M2_SAAL_PARMS saal; } CBI_M2_UPDATE_PARMS; CBI_M2_COMMON_PARMS is documented in Section 6-1-1 of this manual. CBI_M2_MTP2_PARMS is documented in Section 6-1-2 of this manual. CBI_M2_SAAL_PARMS is not used in MTP2 implementations and should be zeroed. Parameters on request. ips_hdr IPS Header. For definition, see Section 6-1-1.
common Common L2 parameters. These fields can be changed on a CBI_M2_UPDATE_PARMS at any time, with the following exceptions: • cong_method, cong_method num_cong_levels and initial_status can be changed only when the link is out of service. • rcv_pool_capacity must never be changed after the first CBI_M2_UPDATE_PARMS signal sent by the L3 to the L2 after registering. mtp2 MTP2-specific parameters.
7. Data Path Routing (DPR) 7-1. dprservice (7D) The DPR service is a part of all protocol support packages for SBE's HighWire boards. The host interface to the DPR service is implemented using the streams putmsg(2) and getmsg(2) calls. Each exchange consists of first a putmsg with the command in the structure sent as the control part of the putmsg and a data buffer if required by the command.
Availability Provided as a component of the SBE HighWire and LinkWARE Support Packages. Commands Commands to the DPR service are sent in the control part of the putmsg call. The first 32-bit integer in the control message's buffer consists of the command to be executed in the low order byte and the value DPR_PROTO_CODE in the next higher byte. Additional parameters for the command follow in the control buffer or, in the case of DPR_WRITE, in the data buffer.
rddata.len = 0; rddata.buf = (char *)buf; flag = 0; if (!(err = getmsg (fd, &rdctl, &rddata, &flag))) { if (!(err = rdproto.rdwr_err)) { /* * If no error, return the amount read. * Set the reference map address for test routines. */ err = rdproto.rdwr_size; } } } return (err); } DPR_WRITE. Writes the DPR connection matrix to the board replacing all current connections.
The elements of the MAP structure are: UINT32 fromDev Source time slot made up by using the macros PUT_TIMESLOT(t) | PUT_CHAN(c) | PUT_DEVICE(d) UINT32 toDev Destination time slot made up by using the above macros UINT32 mode TSI transmission mode for connect as follows: TTSI_LOWLAT Low-latency mode TTSI_FRAMEI Frame-integrity mode TTSI_HOST Host data substitution mode TTSI_IDLE1 Put idle code1 on the TDM highway TTSI_IDLE2 Put idle code2 on the TDM highway TTSI_IDLE3 Put idle code3 on the T
*/ cnctl.maxlen = sizeof (cnproto); cnctl.len = 0; cnctl.buf = (char *)&cnproto; flag = 0; if (!(err = getmsg (fd, &cnctl, 0, &flag))) { err = cnproto.conn_df.df__err } } DPR_DISCONNECT. Disconnects one source time slot from a destination. The putmsg control buffer is a structure of type dpr_conn_t. The conn_map element is a MAP structure that defines the source and destination for the connection.
DPR_IS_TXCONNECTED. Checks if a source device, channel, and timeslot are connected. The putmsg control buffer is a structure of type dpr_srch_t. The srch_conn element is an IOCTLTXRXCONNECT structure that defines the source for the connection. The getmsg control buffer returned is also a dpr_srch_t structure with the error code in the srch_df.df_err element (zero on success).
DPR_PRIMARY_CLOCK. Configures the H.110/CT bus primary clock to use the specified clocking source. The putmsg control buffer is a structure of type dpr_usel_t with the usel_val element specifying the clocking source. The getmsg control buffer returned is also a dpr_usel_t structure with the error code in the usel_err element (zero on success). The allowed clock source values are: T8100_CLK_INTERNAL Run the primary clock from the internal oscillator. T8100_CLK_FRAMEA Run the primary clock from Frame A.
DPR_BUS_CLOCK. Selects a T8102 clock source to drive the local bus. The putmsg control buffer is a structure of type dpr_usel_t with the usel_val element specifying the clocking source. The getmsg control buffer returned is also a dpr_usel_t structure with the error code in the usel_err element, which is zero on success. The allowed clock source values are: T8100_CT_BUS_NO_CLK Do not drive the local bus clock. T8100_CT_BUS_CLK_A Clock A to drive the local bus.
The possible sources for the NETREF are: T8100_CT_BUS_NETREF_SRC_OSC_8 Internal oscillator divided by 8. T8100_CT_BUS_NETREF_SRC_OSC Internal oscillator. T8100_CT_BUS_NETREF_SRC_NETREF_1 Select NETREF1 as input. T8100_CT_BUS_NETREF_SRC_NETREF_2 Select NETREF2 as input. T8100_CT_BUS_NETREF_SRC_LREF0 Comet 0 (Local Reference). T8100_CT_BUS_NETREF_SRC_LREF1 Comet 1 (Local Reference). T8100_CT_BUS_NETREF_SRC_LREF2 Comet 2 (Local Reference). T8100_CT_BUS_NETREF_SRC_LREF3 Comet 3 (Local Reference).
DPR_ENABLE_CLKERR_CALLBACK. Enables the specified clock error watchdogs in the T8102. The putmsg control buffer is a structure of type dpr_cker_t. The cker_evt element is a CLKERREVENT structure that specifies the error watchdogs to enable. The getmsg control buffer returned is also a dpr_cker_t structure with the error code in the cker_df.df_err element (zero on success).
DPR_GET_CLOCK_INFO. Retrieves the current contents of the selected clocking registers in the T8102. The putmsg control buffer is a structure of type dpr_ckin_t with the ckin_par element a T8100_CLOCK_INFO structure that contains only the command. The getmsg control buffer returned is also a dpr_ckin_t structure with the error code in the ckin_err element, which is zero on success.
DPR_MODE. Changes the mode of operation for the Time Slot Interchanger (TSI). The putmsg control buffer is a structure of type dpr_mode_t with the mode_tsi element a IOCTLTSIMODE structure that specifies the mode. The getmsg control buffer returned is also a dpr_mode_t structure with the error code in the mode_df.df_err element, which is zero on success. The elements in the IOCTLTSIMODE structure are: INT32 index The Connection index into the Connection MAP Matrix for this operation, if needed.
UINT32 uiTxStream The Transmit Stream/TSI Highway Number with a valid range of 0 to 31. UINT32 uiRxTimeslot The Host Data to be sent out over the connection. UINT32 uiTxTimeslot IgnoredThe Transmit Time Slot Number with a valid range of 0 to 127. 0 UINT32 uiArg Unused by the DPR_HOST command. _H DPR_IDLE_CODE. Tells the TSI to operate in Idle Code substitution mode.
The elements in the IOCTLTSIMODE are described in DPR_MODE on page 110 except for: uiTSIMode Must be TTSI_TESTPAT. uiRxStream Ignored. uiRxTimeslot Ignored. uiArg A value created using the macro SET_TEST_PATTERN (generate, start, style, pattern, rate) with the following arguments: 112 generate Set to 1 for the TTSI to generate the test pattern, 0 to receive. start Set to 1 to start generation or reception, 0 to stop. style Set to one of the following: TSI_TP_MARK (O.
DPR_READ_DATA_STORE. Reads current incoming data byte in the TSI for the selected highway and time slot. The putmsg control buffer is a structure of type dpr_data_t with the data_tsi element a IOCTLTSIDATASTORE structure that specifies the mode. The getmsg control buffer returned is also a dpr_data_t structure with the error code in the data_df.df_err element, which is zero on success. The data read will be in the element data_tsi.uiData.
DPR_CONN_RPT. Gets a report of the connections. The putmsg control buffer is a structure of type dpr_func_t, which contains only the command. The getmsg control buffer returned is also a dpr_func_t structure with the error code in the df_err element, which is zero on success. The text strings for the report are returned in the data buffer.
DPR_HWY_RPT. Gets a report of the time slot assignments for the specified highway. The putmsg control buffer is a structure of type dpr_usel_t with the usel_val element the number of the specified highway. The getmsg control buffer returned is also a dpr_usel_t structure with the error code in the usel_err element, which is zero on success. The report is returned in the same way as for DPR_CONN_RPT. DPR_PRINT_MATRIX.
7-2. libdpr (3sbe) libdpr provides a set of routines that allow an application to set up and dynamically control time slot connections and clocking operations on all HighWire boards. The DPR service included in the protocol modules downloaded to the HighWire board initializes the Data Path Routing matrix to a functional default configuration.
7-3. sbe_dprOpen Using sbe_dataOpen(3X), this routine opens a connection to the DPR service on the specified board and returns a file descriptor for that connection. It is equivalent to sbe_dataOpen (DPR_SERVICE, Board, 0, oflags). Allowed values for oflags are described in open(2). Synopsis Return values See also #include #include "sbe_dprlib.h" int sbe_dprOpen (int Board, int oflags); On a successful open, sbe_dprOpen returns the number of the file descriptor for the opened connection.
7-6. sbe_dprWrite This routine issues a command to the DPR service to clear out all existing connections and replace them with the number of connections and nmaps specified in the supplied matrix buf. Normally this is only done at system startup with most connections set up and torn down using the DPR_CONNECT and DPR_DISCONNECT commands. Synopsis Return values See also #include "sbe_dprlib.
Arg points to a MAP structure with the following elements: UINT32 fromDev Source time slot made up by using the macros PUT_TIMESLOT(t) | PUT_CHAN(c) | PUT_DEVICE(d) UINT32 toDev Destination time slot made up by using the above macros.
DPR_DISCONNECT. Disconnects connections according to the contents of arg. Arg points to a MAP structure with the same elements as DPR_CONNECT. In this case the connected and ct_xmit_enable elements are not used and the mode element indicates the scope of the disconnect command as follows: SPECIFIED ALL ALL_H110 disconnect just the specified time slot from the source to the destination. disconnect all connections. disconnect all H.110 bus connections. ALL_COMETS disconnect all Comet connections.
DPR_IS_RXCONNECTED. Checks the specified device, channel and time slot to see if it is connected to a transmitting device, channel, and time slot. If so, returns the source device, channel, and time slot. If not, the result index is set to −1. Arg points to a IOCTLTXRXCONNECT structure with the following elements: UINT32 uiDevice Receiving device supplied. UINT32 uiChannel Receiving channel supplied. UINT32 uiTimeslot Receiving time slot supplied.
DPR_FALLBACK_CLOCK. This command configures the H.110/CT bus fallback or secondary clock to the specified source. Arg points to an integer containing one of the values listed below. Note that LREF0 and LREF4 through LREF7 are available only as the primary clock. The secondary clock must be different from the primary clock or an error results. T8100_CLK_INTERNAL Run the secondary clock from the internal oscillator. T8100_CLK_FRAMEA Run the secondary clock from Frame A.
The values for NETREF sources are: T8100_CT_BUS_NETREF_SRC_OSC_8 Internal oscillator divided by 8. T8100_CT_BUS_NETREF_SRC_OSC Internal oscillator. T8100_CT_BUS_NETREF_SRC_NETREF_1 Select NETREF1 as input. T8100_CT_BUS_NETREF_SRC_NETREF_2 Select NETREF2 as input. T8100_CT_BUS_NETREF_SRC_LREF0 Comet 0 (Local Reference). T8100_CT_BUS_NETREF_SRC_LREF1 Comet 1 (Local Reference). T8100_CT_BUS_NETREF_SRC_LREF2 Comet 2 (Local Reference). T8100_CT_BUS_NETREF_SRC_LREF3 Comet 3 (Local Reference).
DPR_ENABLE_CLKERR_CALLBACK. This command enables the specified clock error watchdogs in the T8102 and causes the board to send unsolicited clock error messages to the application on the fildes Stream. The application must either periodically perform non-blocking getmsg(2) calls or set up a task to receive these unsolicited messages. Note that either a DPR_DISABLE_CLKERR_CALLBACK command or a close should be the only DPR actions after issuing this command. Arg points to a CLKERROREVENT structure.
DPR_SET_CLOCK_INFO. This command sets the current contents of selected clocking registers in the T8102. Arg points to a T8100_CLOCK_INFO. DPR_DATA_ALIGNMENT. When there is a change in the Primary Clock, any data subsequently transferred must be re-aligned to the new clock value. This command determines the manner in which this re-alignment takes place.
Arg points to a IOCTLTSIMODE structure with the following elements: INT32 index The Connection index into the Connection MAP Matrix for this operation, if needed. The MAP Element associated with this index will have its mode value updated to reflect the current mode of operation. The index is a signed 32-bit integer and has a valid range of −1 to MAX_CONNECTIONS −1. A value of −1 performs the operation but does not update the mode value in the MAP structure.
DPR_TEST_PATTERN. This command causes the TSI to transmit and receive test patterns, which can be one of the predefined set of patterns included with the TSI, or it can be user defined. Arg points to a IOCTLTSIMODE structure as described in DPR_MODE except for: uiTSIMode Must be TTSI_TESTPAT. usRxTimeslot Ignored. uiRxStream Ignored.
DPR_READ_DATA_STORE. This command returns the current incoming data byte in the TSI for the selected highway and time slot. Arg points to a IOCTLTSIDATASTORE structure with the following elements: UINT32 uiRxHighway The Receive Highway Number. UINT32 uiRxTimeSlot The Receive Time Slot Number. UINT32 uiData The current data returned from the TSI. DPR_CTBUS_ENABLE. This command enables the H.110 bus for clocking and data transmission. No argument is required, so the value of arg should be zero.
7-8. sbe_dprConfigDefault This routine sends a command to the board to reset its configuration to the default set at startup. Synopsis Return values See also #include "sbe_dprlib.h" int sbe_dprConfigDefault (int fildes); On a successful resetting of the DPR configuration, sbe_dprConfigDefault returns a 0. It returns −1 on an error detected by getmsg or putmsg, which sets the global variable errno as appropriate. Otherwise sbe_dprConfigDefault returns an error code as described in dprd_if.
7-11. sbe_dprPrint This routine combines the functions of sbe_dprConnectionReport and sbe_dprHighwayReport by sending a command to the board which then returns text describing both the current connection matrix and the time slots assigned for the supplied highway hwy. This is then printed to standard out. Synopsis Return values See also 130 Data Path Routing (DPR) #include "sbe_dprlib.h" int sbe_dprPrint (int fildes, int hwy); On a successful printing, sbe_dprPrint returns 0.
8. Appendix A: Test and Library Files 8-1. CBI Files The CBI files listed in the following subsections will be installed to /opt/SBEhw/src/cbiptest during the package installation. 8-1-1. CBI library source files (for Solaris) The HighWire_MTP2 release includes the following CBI library source files: • cbiapi.c • cbidclt.c • cbihandl.c • cbimon.c • cbitctl.c • cbitrace.c 8-1-2. CBI include files (for Solaris) The HighWire_MTP2 release includes the following CBI include files for Solaris: • cbi.
8-2. Compiling the CBIPTEST Program To compile the CBITEST program, you may have to modify the Makefile for your local environment and C compiler. Then follow these steps: cd /opt/SBEhw/src/cbiptest make clobber make 8-3. Running the CBIPTEST Program The executables will be stored in ./obj/libcbi.so (library) and ./cbiptest (the test program). Copy the two executables to where they are to be run, if not on this machine.
8-4. Compiling the cbiDemo Program under SDK 1. Copy cbiDemo.c from the distribution to: w:\vxworks\vxhw400\cust_demo 2. Copy cbiDemo.h from the distribution to: w:\common\include\cbi 3. Under the Tornado 2 VxWorks development workspace hw400_sdk_src, hw400_sdk_src add cbiDemo.c to the sdk_sample_applications build. w:\vxworks\vxhw400\cust_demo\cbiDemo.c 4. Under the sdk_sample_applications build, C/C+ compiler tab, add defines: -DINC_DPR -DSABRE_NBASE -DHWMTP2_FOR_SDK 5. Generate/resolve dependencies. 6.
Wait for CBI_M2_OPEN Other msg available, ips_type=0x18800025, ctrl_size=84, data_size=0 Got CBI_M2_OPEN Received CBI_M2_OPEN recv opened Send CBI_M2_REGISTER[0,1] Wait for CBI_M2_REGISTER[0,1] Other msg available, ips_type=0x18800001, ctrl_size=92, data_size=0 Timeslot[1] sender_handle=0x11a0000, receiver_handle=0x1 Received CBI_M2_REGISTER[0,1] Wait for CBI_M2_AVAILABLE[0,1] Other msg available, ips_type=0x18800003, ctrl_size=48, data_size=0 Received CBI_M2_AVAILABLE[0,1] Send CBI_M2_UPDATE_PARMS[0,1] Wai
Other msg available, ips_type=0x18800014, ctrl_size=48, data_size=0 Received CBI_M2_IN_SERVICE[1,1] 1 timeslots, 0.48 seconds, 5000 bytes, 100 data messages 1 timeslots, 2.68 seconds, 10000 bytes, 200 data messages 1 timeslots, 0.60 seconds, 15000 bytes, 300 data messages 1 timeslots, 2.84 seconds, 20000 bytes, 400 data messages 1 timeslots, 0.78 seconds, 25000 bytes, 500 data messages 1 timeslots, 3.06 seconds, 30000 bytes, 600 data messages 1 timeslots, 0.
Port 8 Channel 10 IN_SERVICE!! Port 8 Channel 11 IN_SERVICE!! Port 8 Channel 12 IN_SERVICE!! Port 8 Channel 13 IN_SERVICE!! Port 8 Channel 14 IN_SERVICE!! Port 8 Channel 15 IN_SERVICE!! Port 8 Channel 16 IN_SERVICE!! Port 8 Channel 17 IN_SERVICE!! Port 8 Channel 18 IN_SERVICE!! Port 8 Channel 19 IN_SERVICE!! Port 8 Channel 20 IN_SERVICE!! Port 8 Channel 21 IN_SERVICE!! Port 8 Channel 22 IN_SERVICE!! Port 8 Channel 23 IN_SERVICE!! Port 8 Channel 24 IN_SERVICE!! Port 8 Channel 25 IN_SERVICE!! Port 8 Channel 2
9. Appendix B: Code Values This appendix contains the values assigned to control messages, data types, etc. for the Cross Bus Interface (CBI). 9-1. CBI Function Return Codes These are the return codes from CBI interface functions. Do NOT confuse these with the return codes defined in the CBI_RETURN_CODES that are internal to the actual messages passed across the interface. These codes are relevant only to the Cross Bus Interface. CBI Function Return Codes HighWire MTP-2 - 1.
9-2. CBI Return Codes These are common return codes used on CBI IPSs that flow across the CBI. CBI Return Codes Value CBI_OK 0 CBI_INVALID_TIMER_VALUES 1 CBI_RESOURCE_FAILURE 2 CBI_ABENDED 3 CBI_UNSUCCESSFUL 4 CBI_INVALID_QOS_VALUE 5 CBI_INVALID_STATE 6 CBI_INVALID_CONFIG 7 CBI_ASYNC_COMPLETION 8 9-3. CBI_YES_NO Values for Yes and No. CBI_YES_NO 138 Appendix B: Code Values Value CBI_NO 0 CBI_YES 1 HighWire MTP-2 - 1.
9-4. CBI_MTP2_IPS_TYPES Command codes on messages which are sent from L3 to L2, and visa versa. CBI_MTP2_IPS_TYPES HighWire MTP-2 - 1.
CBI_MTP2_IPS_TYPES Value IPS_CBI_M2_RETRIEVAL_NOT_POSS 0x1880001B IPS_CBI_M2_RETRIEVE_BSNT 0x1880001C IPS_CBI_M2_BSNT 0x1880001D IPS_CBI_M2_BSNT_NOT_RETRIEVABL 0x1880001E IPS_CBI_M2_REM_PROCSSR_OUTAGE 0x1880001F IPS_CBI_M2_REM_PROCSSR_RECOVRD 0x18800020 IPS_CBI_M2_RB_CLEARED 0x18800021 IPS_CBI_M2_RTB_CLEARED 0x18800022 IPS_CBI_M2_CREDIT 0x18800023 IPS_CBI_M2_CREDIT_ERROR 0x18800024 IPS_CBI_M2_OPEN 0x18800025 IPS_CBI_M2_CLOSE 0x18800026 0x18810001 0x18810002 IPS_CBI_M2_MSG_FOR_XMISS
9-6. CBI_M2_LPO_STATES Constants for the local processor outage state reported across the Management Interface. CBI_M2_LPO_STATES Value CBI_M2_LPO_RECOVERED 0x00 CBI_M2_LPO_OUTAGE 0x01 9-7. CBI_M2_UPS_TYPES Constants for “User Proving State” requested by the L3. CBI_M2_UPS_TYPES Value CBI_M2_UPS_NORMAL 0x00 CBI_M2_UPS_EMERGENCY 0x01 9-8. CBI_M2_PS_PROVING_TYPES Constants for the current proving state in use by L2. It is reported on the Link Status indication.
9-9. CBI_M2_EV_TYPES Constants for indication types. See Section 6-3-11 for an explanation of event indications.
9-11. CBI_M2_CONG_LEVELS Constants for the congestion level in use by L2. CBI_M2_CONG_LEVELS Value CBI_M2_CONG_NONE 0x00 CBI_M2_CONG_LEVEL_1 0x01 CBI_M2_CONG_LEVEL_2 0x02 CBI_M2_CONG_LEVEL_3 0x03 9-12. CBI_CONG_CTRL Types of congestion handling. CBI_CONG_CTRL Value CBI_CONG_CTRL_INTERNATIONAL 1 CBI_CONG_CTRL_NATL_WITH_PRI 2 CBI_CONG_CTRL_NATL_BUFFER 3 CBI_CONG_CTRL_NATL_TIMER 4 9-13. CBI_ERR_METHOD Error method. HighWire MTP-2 - 1.
9-14. CBI_XMIT_RATE Transmission rate. Note that CBI_XMIT_RATE_MBITS1_5 is used to denote 1.5 Mbit/s for ITU and 1.536 Mbit/s for ANSI. CBI_XMIT_RATE Value CBI_XMIT_RATE_KBITS4P8 1 CBI_XMIT_RATE_KBITS56 2 CBI_XMIT_RATE_KBITS64 3 CBI_XMIT_RATE_MBITS1_5 4 CBI_XMIT_RATE_MBITS2_0 5 9-15. CBI_IN_SERVICE_MONITOR_TYPES CBI_IN_SERVICE_MONITOR_TYPES Value CBI_IN_SERVICE_SUERM 1 CBI_IN_SERVICE_EIM 2 9-16.
9-17. L1_FRAMING This field specifies the type of framing to set when MTP3 Stub receives M2_OPEN request. These codes are used on the Cross Bus Interface (CBI) only. CBI_L1_FRAMING Value CBI_L1_FRAMING_NONE 0 CBI_L1_FRAMING_E1 1 CBI_L1_FRAMING_T1 2 9-18. L1_CLOCKING This field specifies the type of clocking to use on the L1 framers. Used on Cross Bus Interface (CBI) only. CBI_L1_CLOCKING Value CBI_L1_CLOCKING_LOOP 1 CBI_L1_CLOCKING_LOCAL 2 CBI_L1_CLOCKING_THROUGH 3 9-19.
9-20. L1_LINE_CODE This field specifies the line code for each of the framers on the line card. CBI_L1_LINE_CODE Value CBI_HM_DS1_PHYS_ENC_B8ZS 1 CBI_HM_DS1_PHYS_ENC_AMI 2 CBI_HM_DS1_PHYS_ENC_HDB3 3 9-21. L1_LINE_BUILD_OUT This field specifies the line build out for each of the framers on the line card. In E1, this is the line impedance. In T1, it is the line length in feet.
10. Appendix C: Manpages Manpages in HTML format are available on the CDROM. These files are located in the directory off of the CDROM's main directory. The front page of the CDROM has a reference link to the manpage index file . When the package is installed on a system, the manpages index and files can be found at directory as a file . The manpages are also installed in nroff format in the standard user man directories.
Table 10-1 Manpages (continued) Data Path Routing Functions libdpr (3SBE) SBE HighWire Data Path Routing (DPR) Service Support Package sbe_dprOpen(3SBE) open a connection to the DPR service sbe_dprClose(3SBE) close a connection to the DPR service sbe_dprRead(3SBE) read the current DPR connection matrix sbe_dprWrite(3SBE) write the supplied DPR connection matrix and make it the current one sbe_dprIoctl(3SBE) change individual DPR connections and dynamic parameters sbe_dprConfigDefault(3SBE) set
11. Appendix: cbiDemo.c and dprDemo.c 11-1. cbiDemo.c The cbiDemo.c file can be used as the framework for applications which transport data across the HighWire MTP2 CBI Interface. The file is located at /opt/SBEhw/src/cbi_demo/... and is installed by the HighWire MTP2 Software Package. The directory also contains all required elements needed to recompile the application.
Appendix: cbiDemo.c and dprDemo.c HighWire MTP-2 - 1.
