|
| Top | Log In | Cart Contents | Checkout |
|
X.25 Development Kit For Linux and 'BSD Un*xTable of Contents
The X.25 Packet HandlerThe ET/PCX.25 level 3 driver is a state machine implementation of the X.25 packet layer protocol compatible with the widely accepted CCITT recommendations. Functionally, the driver retrieves frames from the communication board and passes them to the level 3 packet handler. The packet handler performs the required functions and passes user data and event indications to the user interface. Control packets pertinent to protocol processing are transmitted automatically, without user intervention. All variable management, state changes, data buffering and error control is handled by the driver without user intervention. The API (Application Interface) utilizes system work areas (dynamically allocated at installation time) which provide the user with the necessary interface for monitoring and controlling driver activity. The packet handler is completely interrupt driven, producing real-time background performance while maintaining the ability to process user commands in a multi-user, multi-tasking environment. Driver Configuration The X.25 driver configuration files (described in the Installation and Configuration Manual) contain configurable parameters and default values for the communication board and the X.25 level 3 environment. . Macros Macros (described later in the library section of this document) are provided in x25user.h for variables most often needed for program development. Following are some examples of macro usage: Examples: LCN(x) - the logical channel of the file descriptor x. STATE(x) - the current state of the logical channel x. if (STATE(lcnfd) == STATE_D1) printf(“Channel %d is in STATE D1”,LCN(lcnfd)); It is highly recommended that the macros be used for all levels of program development, both for readability and compatibility with future releases of this product. IMPORTANT NOTE: The plcn_wa and psys_wa variables utilized by library functions must be initialized to their proper values (by a successful open_x25()) before using any macros or library functions. It is imperative that these variables not be modified or redefined by the programmer, as proper operation of the library functions are dependent on their values.
Getting StartedConfiguring ET/HDLC for X.25 Operation Before utilizing the development kit, you must install the X.25 subsystem into your computer. The "environment" sets up your default X.25 channel mappings in accordance with configuration information that you provide. You must obtain the configuration information from your network provider in order to properly utilize the X.25 network. Installing the Driver In Linux the driver is implemented as a loadable module and is loaded with the insmod command. Details for loading the driver can be found in the Linux HDLC Manual. The 'BSD driver requires that you install the driver modules into your kernel. Details for doing this can be found in the BSD HDLC Manual. Configuring and Starting the X.25 Driver Subsystem Once the driver is successfully installed, the X.25 driver is configured by running the program x25start, which is in the /usr/x25/utils directory of the distribution. The x25start command line requires that you indicate the name of the configuration file that defines your system. Example: /usr/x25/utils/x25start /usr/x25/utils/x25sys.cfg followed by a carriage return. The head configuration file (default x25sys.cfg) has a format as follows:
More about x25start below. Using x25start to Initialize X.25 Subsystem In order to run the X.25 protocol on any of your installed HDLC lines, you must run a startup utility that initializes a global state-machine and sets up a working environment for protocol management. A startup utility is provided which will configure all of your installed X.25 lines and also initialize the system environment based on your configuration parameters. The utility, /usr/x25/utils/x25start requires a system configuration file which must contain information about how many X.25 lines are installed in your system along with the configuration parameters for each of the lines. For a detailed description of the configuration file formats, see the ET/HDLC Installation and Configuration Manual. After you've set up your configuration files, to start the X.25 subsystem, simply enter the following: /usr/x25/utils/x25start /usr/x25/utils/x25sys.cfg All lines defined in x25sys.cfg will be initialized and the utility will attempt to bring up all of the links. Upon successful completion, all of the X.25 lines will be ready for operation. Writing Basic X.25 Applications There is a basic framework for writing X.25 applications with the development kit that, if followed, will make writing applications much easier. The basic structure is as follows:
Some sample code which achieves this might be as follows:
and so forth. Using the Event Manager The framework of the development system centers on building event driven utilities with the event manager. When you call x25_setnotify(), it tells the driver to queue events from the internal event manager and store them in a queue accessable by user level programs. When your application calls et_l3getevt(), the event is retrieved from the channel specified. The above example will get events from the entire line. If you are writing multi-channel applications that will be controlled by a single application this is the most efficient way to do it. Dynamic applications that use SVCs will not know the channel they are on until a call is made or an incoming call arrives. Utilizing PVCs (Permanent Virtual Circuits) In order to use PVCs you must know the channel on which data will arrive. If you know the channel number that is used you can get the lcnfd with the find_lcn() function. Usage of this function is as follows:
and so on. You could also setup notification on the entire line as in the previous example, but you'd have to check to make certain that the data was on the proper lcn if you had multiple channels in use. Setting up SVCs (Switched Virtual Circuits) An SVC is a dynamic connection that can be initialed by your application or a remote application. Below is a brief discussion of the mechanisms involved with managing dynamic virtual circuits. General Access: Making Calls and Sending Data The basic function of any communications protocol is to pass data, and X.25 is no different. The ET/PCX.25 interface attempts to simplify this process as much as possible, but there are certain fundamental concepts which should be understood before any significant development (or design) is attempted. Making Calls The X.25 protocol allows for the establishment of multiple logical connections on a single physical line by segregating packets on logical channels. A logical channel number is attached to each packet, telling the network or receiving device for which connection the packet is intended. In order to initiate the establishment of a connection, you must issue a CALL packet to the network. The call packet must contain the logical network address of the destination device, as well as special facilities for the connection. In addition, the logical channel number that you want to establish the call on must also be specified. In ET/PCX.25, calls are initiated by the make_call() function. In the simplest case, the application will call make_call() specifying the destination address and a 0 (the server lcnfd for line 0) in the first field (lcnfd..see make_call()). The 0 tells make_call() to issue the call packet on the highest numbered available channel. For example: lcnfd=make_call(0,”5551212",””,””,””,0); will issue a CALL packet on the next highest available channel with a destination address of 5551212. If you wanted to issue a call on a particular channel, you would replace the 0 with the number of the lcnfd which corresponds to the channel. For instance, if your logical channel numbers start at 1 and you wanted to make a call on channel 4, your call would look like this: lcnfd=make_call(4,”5551212",””,””,””,0); remember that parameter accepted by X.25 functions is what we call a "lcnfd", which is not necessarily equivalent to the logical channel number. In view of this, a more correct what to implement the above would be: lcnfd=make_call(find_lcn(line,4),"5551212","","","",0); Transferring Data Once you’ve established a connection, you can read and write data on the channel via the write_data(), snd_data(), and read_data() functions. These functions are very similar to the read() and write() functions for accessing files, the only difference is that the concept of packetization should be considered with the X.25 calls, and that the X.25 functions are only valid when a connection exists on the specified descriptor. The read_data() function allows for data to be read transparently from the level 3 data queues. read_data() never blocks, and single bytes of data can be read without any adverse effect on communications. The snd_data() function is a level 3 primitive function which simply envelopes the data presented in an X.25 data packet and attempts to queue the packet for transmit. snd_data() will not accept data larger than the maximum packet size. An interesting note is that snd_data() will return immediately if the level 3 window is closed, allowing an application to do something else while waiting for the window to open. write_data() is a higher level function which accepts any amount of data and builds the largest possible packets, and will wait (up to WR_TMO()) seconds in the event of a window closure. When write_data() is called with the M_BIT flag set, the M bit will be set in all packets except for the last packet. Receiving Data Data is always received in "packets" exactly as the data was received. When issuing calls to read_data() the buffer supplied should be large enough to accommodate a complete packet. If "flag append mode" (set with x25_flappend()) is set, the trailing byte of the packet will contain flags that indicate whether the M, D and Q-bits were set in the associated packet. Typically this mode would need to be used in any application that utilized any of these special bits. Controlling RR Packet Transmission The X.25 protocol provides a “windowing” mechanism which provides for intrinsic flow control of the transmission of DATA packets. While this powerful feature enables devices with substantially different throughput capabilities to communicate without the possibility of data loss, the algorithm used to “slide” the window can have a dramatic effect on performance. Depending on the application, the algorithm used to send RR packets can stifle or streamline performance. It is important to note that, as many pseudo-experts may indicate, RR packets are NOT acknowledgements of data packets. Other than with the D-bit procedure, there is no requirement in the protocol that an RR follow a DATA packet, and an application may terminate without sending an RR at all. An RR packet simply indicates to the network (or other connected device) that resources have been made available for additional data packets. ET/PCX.25 provides the following RR algorithms under user control. Macros for these algorithms can be found in x25user.h: RRF_M0 - send an RR whenever a resource is freed. The default and safest algorithm. Anyone who is not an expert in the X.25 protocol should avoid using the RRF_DONT mode, but other modes can be used without too much chance of adverse effect. Note that specifying an algorithm out of the window (for instance specifying RRF_M4 when the actual window is only 2) will have the effect of using RRF_M0. Programmers should note that the default algorithm (RRF_M0) will be re-established whenever a new virtual circuit is established (whenever a CALL CONFIRMATION is sent or received). It is the responsibility of the application to set the RR algorithm after the call is established. All system work areas are accessible by the programmer via the system variable plcn_wa, which is a pointer to an array of work area pointers. Each pointer in this array points to a logical channel work area structure, which contains variables specific to a particular logical channel. The first member of the array (plcn_wa[0]) points to the server work area structure for line 0 (type SYS_WA, defined in x25user.h), and is used to store variables which are not logical channel dependent (default window sizes, number of X.25 lines, etc.). A separate variable psys_wa is provided to simplify de-referencing of this structure. Be careful to properly document any low level programming, and utilize MACROS whenever possible. All system macros defined by Emerging Technologies will either be supported or eliminated in future product revisions, but work area variables may be changed periodically to support new implementations and functions. As a general rule, you should not use low level access unless absolutely necessary and, if you do, you should check for compatibility whenever a new release is received. Logical channel file descriptors (lcnfd) used for logical channel related operations that are returned by the functions make_call() and get_call() (for SVCs) are indexes into these work areas. In order to access PVCs (which do not allow calls), you will have to determine the lcnfd for each of you PVCs. If your logical channel numbers start at 1 and are contiguous, then file descriptor numbers should correspond to LCNs (for line 0). If you cannot manually determine your logical channel mappings, you can determine the logical channel number of each descriptor with the LCN() macro. For Example: For (lcnfd=0;lcnfd < MAX_LCNFD;lcnfd++){
} will display the logical channel mappings on the screen. As an example of usage of work area level access, suppose you wanted to check for available data in the level 3 receive queue on logical channel 16 (when your channel numbers start at 1) without removing any data from the queue (read_data() would remove data). Some sample ‘C’ code might look like this: In MS-DOS: if (plcn_wa[16]->state == STATE_D1)
} In LINUX or BSD unix: lcnfd=16;
} When multiple X.25 lines are being used, file descriptor management is slightly more complicated. As far as the X.25 work area environment is concerned, each line is grouped on top of the previous line, so that all references to channels on a particular line may be referenced relative to the system server file descriptor for that line. For example, an environment with 2 X.25 lines might look like this:
The macro LINE_FD(line) returns the server file descriptor for the requested line. In the above example LINE_FD(1) would return 17, and logical channel numbers on this line may be referenced using 17+LCN. Macros (described later in the library section of this document) are provided in x25user.h for variables most often needed for program development. Following are some examples of macro usage: Examples: LCN(x) - the logical channel of the file descriptor x.
is equivalent to: if (plcn_wa[lcnfd]->state == 10)
It is highly recommended that the macros be used for all levels of program development, both for readability and compatibility with future releases of this product. IMPORTANT NOTE: The plcn_wa and psys_wa variables utilized by library functions must be initialized to their proper values (by a successful open_x25()) before using any macros or library functions. It is imperative that these variables not be modified or redefined by the programmer, as proper operation of the library functions are dependent on their values. To view the X.25 macro reference, click here. Compiling and Linking Applications on Linux and 'BSD systems On unix systems the library hdlclib.a is supplied and is resident in /usr/hdlc/lib/hdlclib.a. The hdlc and X.25 functions are all contained in one libary. To link an application use the following: cc -c -Dunix -DLINUX -DBSD386 yourapp.c please refer the the makefile provide for switches are required for your particular OS. Debugging with X25_TRACE (MS-DOS only) When a problem exists in an X.25 environment, it is often useful to “see” what’s going on on the communications line. If you work in a communications laboratory, you’ll probably have an expensive line analyzer to help debug protocol problems. If you don’t happen to have an analyzer handy, ET/PCX.25 provides a tracing capability that decodes and displays incoming and outgoing packets on your screen. Note that X25_TRACE displays frames that are received by the communications interface, but can only display what is being submitted to the communications board. If the link is down or there is a physical communications problem, the packets displayed by X25_TRACE will not actually be transmitted on the line. To use the X.25 trace feature, just set the macro X25_TRACE to TRUE. Incoming packets are displayed on the console preceded by “r “. Outgoing packets are preceded by “t “. Here’s how to turn on the trace feature programatically in MSDOS: X25_TRACE=TRUE; In LINUX and BSD UNIX, you can enable debugging with the debugx25 utility. Sample display:
|
Bandwidth Control
Demos