libisdn
Q921.h
Go to the documentation of this file.
00001 /*****************************************************************************
00002 
00003   FileName:     q921.h
00004 
00005   Description:  Contains headers of a Q.921 protocol.
00006 
00007   Note:         This header file is the only include file that should be
00008                 acessed by users of the Q.921 stack.
00009 
00010   Interface:    The Q.921 stack contains 2 layers.
00011 
00012                 -   One interface layer.
00013                 -   One driver layer.
00014 
00015                 The interface layer contains the interface functions required
00016                 for a layer 2 stack to be able to send and receive messages.
00017 
00018                 The driver layer will simply feed bytes into the ship as
00019                 required and queue messages received out from the ship.
00020 
00021                 Q921TimeTick        The Q.921 like any other blackbox
00022                                     modules contains no thread by it's own
00023                                     and must therefore be called regularly
00024                                     by an external 'thread' to do maintenance
00025                                     etc.
00026 
00027                 Q921Rx32            Receive message from layer 3. Called by
00028                                     the layer 3 stack to send a message.
00029 
00030 
00031                                 NOTE: The following are not yet implemented
00032 
00033                 OnQ921Error         Function called every if an error is
00034                                     detected.
00035 
00036                 OnQ921Log           Function called if logging is active.
00037 
00038 
00039                 <TODO> Maintenance/Configuration interface
00040                                 <TODO> Logging
00041                                 <TODO> DL_ message passing to layer 3
00042                                 <TODO> Timers
00043                                 <TODO> Api commands to tell 921 to stop and start for a trunk
00044 
00045   Created:      27.dec.2000/JVB
00046 
00047   License/Copyright:
00048 
00049   Copyright (c) 2007, Jan Vidar Berger, Case Labs, Ltd. All rights reserved.
00050   email:janvb@caselaboratories.com
00051 
00052   Redistribution and use in source and binary forms, with or without
00053   modification, are permitted provided that the following conditions are
00054   met:
00055 
00056     * Redistributions of source code must retain the above copyright notice,
00057           this list of conditions and the following disclaimer.
00058     * Redistributions in binary form must reproduce the above copyright notice,
00059           this list of conditions and the following disclaimer in the documentation
00060           and/or other materials provided with the distribution.
00061     * Neither the name of the Case Labs, Ltd nor the names of its contributors
00062           may be used to endorse or promote products derived from this software
00063           without specific prior written permission.
00064 
00065   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00066   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00067   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00068   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00069   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00070   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00071   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00072   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00073   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00074   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00075   POSSIBILITY OF SUCH DAMAGE.
00076 
00077 *****************************************************************************/
00078 
00079 /****************************************************************************
00080  * Changes:
00081  *
00082  * - June,July 2008: Stefan Knoblich <s.knoblich@axsentis.de>:
00083  *     Add PTMP TEI management
00084  *     Add timers
00085  *     Add retransmit counters
00086  *     Add logging
00087  *     Various cleanups
00088  *
00089  * - April 2009: Stefan Knoblich <s.knoblich@axsentis.de>:
00090  *     More cleanups
00091  *     Doxygen documentation
00092  *
00093  ****************************************************************************/
00094 
00095 #ifndef _Q921_H_
00096 #define _Q921_H_
00097 
00098 #include "Q9XXplatform.h"
00099 
00100 #define Q921_STATISTICS
00101 #define Q921_STATISTICS_EXTENDED
00102 
00103 #define Q921MAXHDLCSPACE 3000
00104 #define L2UCHAR         unsigned char           /* Min 8 bit                    */
00105 #define L2USHORT        unsigned short          /* 16 bit                       */
00106 #define L2INT           int                     /* Min 16 bit signed            */
00107 #define L2ULONG         unsigned long           /* Min 32 bit                   */
00108 #define L2TRUNK         Q921Data_t *
00109 
00110 #define Q921_TEI_BCAST          127
00111 #define Q921_TEI_MAX            Q921_TEI_BCAST
00112 
00113 #define Q921_TEI_DYN_MIN        64
00114 #define Q921_TEI_DYN_MAX        126
00115 
00116 
00120 typedef enum
00121 {
00122         Q921_TE = 0,            
00123         Q921_NT = 1             
00124 } Q921NetUser_t;
00125 
00129 typedef enum
00130 {
00131         Q921_PTP  = 0,          
00132         Q921_PTMP = 1           
00133 } Q921NetType_t;
00134 
00138 typedef enum
00139 {
00140         Q921_LOG_NONE  = -1,
00141         Q921_LOG_EMERG =  0,
00142         Q921_LOG_ALERT,
00143         Q921_LOG_CRIT,
00144         Q921_LOG_ERROR,
00145         Q921_LOG_WARNING,
00146         Q921_LOG_NOTICE,
00147         Q921_LOG_INFO,
00148         Q921_LOG_DEBUG
00149 } Q921LogLevel_t;
00150 
00151 /*
00152  * Messages for L2 <-> L3 communication
00153  */
00154 typedef enum {
00155         Q921_DL_ESTABLISH = 0,
00156         Q921_DL_ESTABLISH_CONFIRM,
00157         Q921_DL_RELEASE,
00158         Q921_DL_RELEASE_CONFIRM,
00159         Q921_DL_DATA,
00160         Q921_DL_UNIT_DATA
00161 } Q921DLMsg_t;
00162 
00163 typedef int (*Q921Tx21CB_t) (void *, L2UCHAR *, L2INT);
00164 typedef int (*Q921Tx23CB_t) (void *, Q921DLMsg_t ind, L2UCHAR tei, L2UCHAR *, L2INT);
00165 typedef int (*Q921LogCB_t)  (void *, Q921LogLevel_t, char *, L2INT);
00166 
00167 struct Q921_Link;
00168 
00169 #ifdef Q921_STATISTICS
00170 enum {
00171         Q921_STATS_NONE = 0,
00172 
00173         /* state changes */
00174         Q921_STATS_ST01,
00175         Q921_STATS_ST02,
00176         Q921_STATS_ST03,
00177         Q921_STATS_ST04,
00178         Q921_STATS_ST05,
00179         Q921_STATS_ST06,
00180         Q921_STATS_ST07,
00181         Q921_STATS_ST08,
00182 
00183         /* timer events */
00184         Q921_STATS_T200,
00185         Q921_STATS_T201,
00186         Q921_STATS_T202,
00187         Q921_STATS_T203,
00188 
00189         Q921_STATS_TM01,
00190 
00191         /* limit / counter overruns */
00192         Q921_STATS_N200,
00193         Q921_STATS_N201,
00194         Q921_STATS_N202,
00195 
00196 #ifdef Q921_STATISTICS_EXTENDED
00197         /* packet send counter */
00198         Q921_STATS_SEND_S,
00199         Q921_STATS_SEND_U,
00200         Q921_STATS_SEND_I,
00201 
00202         Q921_STATS_SEND_DISC,
00203         Q921_STATS_SEND_DM,
00204         Q921_STATS_SEND_REJ,
00205         Q921_STATS_SEND_RR,
00206         Q921_STATS_SEND_RNR,
00207         Q921_STATS_SEND_SABME,
00208         Q921_STATS_SEND_UA,
00209         Q921_STATS_SEND_UN,
00210 
00211         /* packet receive counter */
00212         Q921_STATS_RECV_S,
00213         Q921_STATS_RECV_U,
00214         Q921_STATS_RECV_I,
00215 
00216         Q921_STATS_RECV_DISC,
00217         Q921_STATS_RECV_DM,
00218         Q921_STATS_RECV_REJ,
00219         Q921_STATS_RECV_RNR,
00220         Q921_STATS_RECV_RR,
00221         Q921_STATS_RECV_SABME,
00222         Q921_STATS_RECV_UA,
00223         Q921_STATS_RECV_UN,
00224 
00225         Q921_STATS_RECV_INVALID_S,
00226         Q921_STATS_RECV_INVALID_U,
00227         Q921_STATS_RECV_INVALID_I,
00228 
00229         /* TEI-management counter */
00230         Q921_STATS_TEI_SEND_AR,         
00231         Q921_STATS_TEI_SEND_AS,         
00232         Q921_STATS_TEI_SEND_CR,         
00233         Q921_STATS_TEI_SEND_CS,         
00234         Q921_STATS_TEI_SEND_DS,         
00235         Q921_STATS_TEI_SEND_RR,         
00236         Q921_STATS_TEI_SEND_VR,         
00238         Q921_STATS_TEI_RECV_AR,         
00239         Q921_STATS_TEI_RECV_AS,         
00240         Q921_STATS_TEI_RECV_CR,         
00241         Q921_STATS_TEI_RECV_CS,         
00242         Q921_STATS_TEI_RECV_RR,         
00243         Q921_STATS_TEI_RECV_VR,         
00244 #endif
00245         /* don't touch */
00246         Q921_STATS_MAX
00247 };
00248 #endif
00249 
00254 typedef struct Q921Data
00255 {
00256         L2INT initialized;
00257 
00258         L2UCHAR sapi;                   
00259         L2UCHAR tei;                    
00261         L2INT Q921HeaderSpace;
00262         Q921NetUser_t NetUser;
00263         Q921NetType_t NetType;
00264 
00265         struct Q921_Link *context;      
00267         /* timers */
00268         L2ULONG T202;                   
00269         L2ULONG T200Timeout;
00270         L2ULONG T201Timeout;
00271         L2ULONG T202Timeout;
00272         L2ULONG T203Timeout;
00273 
00274         L2ULONG TM01Timeout;
00275 
00276         /* counters */
00277         L2ULONG N200Limit;              
00279         L2ULONG N202;                   
00280         L2ULONG N202Limit;              
00282         L2ULONG N201Limit;              
00283         L2ULONG k;                      
00285         /* callbacks and callback data pointers */
00286         Q921Tx21CB_t Q921Tx21Proc;
00287         Q921Tx23CB_t Q921Tx23Proc;
00288         void *PrivateData21;
00289         void *PrivateData23;
00290 
00291         /* logging */
00292         Q921LogLevel_t  loglevel;       
00293         Q921LogCB_t     Q921LogProc;    
00294         void *PrivateDataLog;           
00296         /* tei mgmt */
00297         L2UCHAR tei_map[Q921_TEI_MAX];  
00299         L2UCHAR HDLCInQueue[Q921MAXHDLCSPACE];  
00300 } Q921Data_t;
00301 
00319 Q921_API int Q921_InitTrunk(L2TRUNK trunk,
00320                                         L2UCHAR sapi,
00321                                         L2UCHAR tei,
00322                                         Q921NetUser_t NetUser,
00323                                         Q921NetType_t NetType,
00324                                         L2INT hsize,
00325                                         Q921Tx21CB_t cb21,
00326                                         Q921Tx23CB_t cb23,
00327                                         void *priv21,
00328                                         void *priv23);
00333 Q921_API int Q921Start(L2TRUNK trunk);
00334 
00339 Q921_API int Q921Stop(L2TRUNK trunk);
00340 
00347 Q921_API void Q921SetLogCB(L2TRUNK trunk, Q921LogCB_t func, void *priv);
00348 
00354 Q921_API void Q921SetLogLevel(L2TRUNK trunk, Q921LogLevel_t level);
00355 
00361 Q921_API Q921LogLevel_t Q921GetLogLevel(L2TRUNK trunk);
00362 
00368 Q921_API const char * Q921GetLogLevelName(L2TRUNK trunk);
00369 
00375 Q921_API int Q921Rx12(L2TRUNK trunk);
00376 
00385 Q921_API int Q921Rx32(L2TRUNK trunk, Q921DLMsg_t ind, L2UCHAR tei, L2UCHAR * Mes, L2INT Size);
00386 
00393 Q921_API int Q921QueueHDLCFrame(L2TRUNK trunk, L2UCHAR *b, L2INT size);
00394 
00399 Q921_API void Q921SetGetTimeCB(L2ULONG (*callback)(void));
00400 
00405 Q921_API void Q921TimerTick(L2TRUNK trunk);
00406 
00412 Q921_API int Q921Establish(L2TRUNK trunk, L2UCHAR tei);
00413 
00419 Q921_API int Q921Release(L2TRUNK trunk, L2UCHAR tei);
00420 
00426 Q921_API int Q921IsEstablished(L2TRUNK trunk, L2UCHAR tei);
00427 
00433 #ifdef Q921_STATISTICS
00434 
00438 struct Q921StatsCounter
00439 {
00440         const int  id;
00441         const char *name;
00442         const char *desc;
00443 };
00444 
00453 Q921_API void Q921StatsCounterResetAll(L2TRUNK trunk, const int tei);
00454 
00464 Q921_API void Q921StatsCounterReset(L2TRUNK trunk, const int id, const int tei);
00465 
00472 Q921_API const struct Q921StatsCounter *Q921StatsCounterFirst(void);
00473 Q921_API const struct Q921StatsCounter *Q921StatsCounterNext(const struct Q921StatsCounter *cur);
00474 
00485 Q921_API unsigned int Q921StatsCounterValue(const L2TRUNK trunk, const struct Q921StatsCounter *counter, const int tei);
00486 
00494 Q921_API int Q921StatsCounterID(const struct Q921StatsCounter *counter);
00495 
00503 Q921_API const char *Q921StatsCounterName(const struct Q921StatsCounter *counter);
00504 
00512 Q921_API const char *Q921StatsCounterDescription(const struct Q921StatsCounter *counter);
00513 
00521 Q921_API int Q921StatsCounterIsGlobal(const struct Q921StatsCounter *counter);
00522 
00530 Q921_API int Q921StatsCounterIsError(const struct Q921StatsCounter *counter);
00531 
00540 Q921_API int Q921StatsCounterIsAvailable(const L2TRUNK trunk, const struct Q921StatsCounter *counter);
00541 
00557 #define Q921StatsCounterForeach(name)   \
00558         for (const struct Q921StatsCounter * name = Q921StatsCounterFirst(); name; name = Q921StatsCounterNext(name))
00559 
00568 Q921_API const char * Q921StatsCounterGetDescription(const int id);
00569 Q921_API const char * Q921StatsCounterGetName(const int id);
00570 Q921_API int Q921StatsCounterGetIsGlobal(const int id);
00571 Q921_API unsigned int Q921StatsCounterGetValue(const L2TRUNK trunk, const int id, const int tei);
00572 
00575 #endif
00576 
00578 #endif /* _Q921_H_ */