contrib/ngatm/man/unisap.3

   1 .\"
   2 .\" Copyright (c) 2004-2005
   3 .\"     Hartmut Brandt.
   4 .\"     All rights reserved.
   5 .\" Copyright (c) 2001-2003
   6 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   7 .\"     All rights reserved.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  31 .\"
  32 .\" $Begemot: libunimsg/man/unisap.3,v 1.5 2005/06/15 11:37:11 brandt_h Exp $
  33 .\"
  34 .Dd June 14, 2005
  35 .Dt UNISAP 3
  36 .Os
  37 .Sh NAME
  38 .Nm unimsg ,
  39 .Nm unisve_check_addr ,
  40 .Nm unisve_check_selector ,
  41 .Nm unisve_check_blli_id2 ,
  42 .Nm unisve_check_blli_id3 ,
  43 .Nm unisve_check_bhli ,
  44 .Nm unisve_check_sap ,
  45 .Nm unisve_overlap_addr ,
  46 .Nm unisve_overlap_selector ,
  47 .Nm unisve_overlap_blli_id2 ,
  48 .Nm unisve_overlap_blli_id3 ,
  49 .Nm unisve_overlap_bhli ,
  50 .Nm unisve_overlap_sap ,
  51 .Nm unisve_is_catchall ,
  52 .Nm unisve_match
  53 .Nd "ATM signalling library - ATM SAP handling"
  54 .Sh LIBRARY
  55 Begemot ATM signalling library
  56 .Pq libunimsg, -lunimsg
  57 .Sh SYNOPSIS
  58 .In uni4/unisap.h
  59 .Ft int
  60 .Fn unisve_check_addr "const struct unisve_addr *sve"
  61 .Ft int
  62 .Fn unisve_check_selector "const struct unisve_selector *sve"
  63 .Ft int
  64 .Fn unisve_check_blli_id2 "const struct unisve_blli_id2 *sve"
  65 .Ft int
  66 .Fn unisve_check_blli_id3 "const struct unisve_blli_id3 *sve"
  67 .Ft int
  68 .Fn unisve_check_bhli "const struct unisve_bhli *sve"
  69 .Ft int
  70 .Fn unisve_check_sap "const struct uni_sap *sve"
  71 .Ft int
  72 .Fn unisve_overlap_addr "const struct unisve_addr *sve1" "const struct unisve_addr *sve2"
  73 .Ft int
  74 .Fn unisve_overlap_selector "const struct unisve_selector *sve1" "const struct unisve_selector *sve2"
  75 .Ft int
  76 .Fn unisve_overlap_blli_id2 "const struct unisve_blli_id2 *sve1" "const struct unisve_blli_id2 *sve2"
  77 .Ft int
  78 .Fn unisve_overlap_blli_id3 "const struct unisve_blli_id3 *sve1" "const struct unisve_blli_id3 *sve2"
  79 .Ft int
  80 .Fn unisve_overlap_bhli "const struct unisve_bhli *sve1" "const struct unisve_bhli *sve2"
  81 .Ft int
  82 .Fn unisve_overlap_sap "const struct uni_sap *sap1" "const struct uni_sap *sap2"
  83 .Ft int
  84 .Fn unisve_is_catchall "const struct uni_sap *sap"
  85 .Ft int
  86 .Fn unisve_match "const struct uni_sap *sap" \
  87 "const struct uni_ie_called *called" "const struct uni_ie_blli *blli" \
  88 "const struct uni_ie_bhli *bhli"
  89 .Sh DESCRIPTION
  90 The
  91 .Nm
  92 library contains functions to handle Service Access Points (SAP) and SAP Vector
  93 Elements (SVE) as specified in the ATM Forum ATM API Semantic Description.
  94 SAPs are the analog of TCP and UDP ports in the ATM world.
  95 As usually in ATM they are a couple of orders of magnitude more complex as
  96 their Internet equivalent.
  97 See the ATM Forum document for a description.
  98 .Pp
  99 A SAP is a data structure:
 100 .Bd -literal -offset indent
 101 struct uni_sap {
 102         struct unisve_addr      addr;
 103         struct unisve_selector  selector;
 104         struct unisve_blli_id2  blli_id2;
 105         struct unisve_blli_id3  blli_id3;
 106         struct unisve_bhli      bhli;
 107 };
 108 .Ed
 109 .Pp
 110 that consists of 5 elements matching different information elements in
 111 the SETUP message.
 112 Each of these elements has a tag that defines how the SVE is to be matched
 113 with the information element.
 114 The tag is one of
 115 .Bl -tag -width ".Dv UNISVE_PRESENT"
 116 .It Dv UNISVE_ABSENT
 117 The information element has to absent from the SETUP message.
 118 .It Dv UNISVE_PRESENT
 119 The information element has to be present in the SETUP message and must
 120 match the SVE.
 121 .It Dv UNISVE_ANY
 122 The information element may be absent from the SETUP message or may
 123 have any value.
 124 .El
 125 .Pp
 126 The called address is matched by a
 127 .Bd -literal -offset indent
 128 struct unisve_addr {
 129         enum unisve_tag tag;
 130         enum uni_addr_type type;/* type of address */
 131         enum uni_addr_plan plan;/* addressing plan */
 132         uint32_t        len;    /* length of address */
 133         u_char          addr[UNI_ADDR_MAXLEN];
 134 };
 135 .Ed
 136 .Pp
 137 Here
 138 .Fa type
 139 is the type of address and
 140 .Fa plan
 141 is the address plan.
 142 .Fa len
 143 is the length of the address (for ATME addresses not counting the selector byte)
 144 and
 145 .Fa addr is the address itself.
 146 .Pp
 147 In case of ATME addresses the selector byte is matched by a
 148 .Bd -literal -offset indent
 149 struct unisve_selector {
 150         enum unisve_tag tag;
 151         uint8_t         selector;
 152 };
 153 .Ed
 154 .Pp
 155 Here
 156 .Fa selector
 157 is the selector byte that must match the 20th byte of the ATME calling address
 158 from the SETUP message.
 159 .Pp
 160 The BLLI information element is matched by two SVEs: one for layer 2 options
 161 and one for layer 3 options.
 162 The layer 2 SVE is:
 163 .Bd -literal -offset indent
 164 struct unisve_blli_id2 {
 165         enum unisve_tag tag;
 166         uint8_t         proto:5;/* the protocol */
 167         uint8_t         user:7; /* user specific protocol */
 168 };
 169 .Ed
 170 .Pp
 171 Where the
 172 .Fa user
 173 fields is matched only if the
 174 .Fa proto
 175 field specifies
 176 .Dv UNI_BLLI_L2_USER .
 177 The layer 3 SVE is:
 178 .Bd -literal -offset indent
 179 struct unisve_blli_id3 {
 180         enum unisve_tag tag;
 181         uint8_t         proto:5;/* L3 protocol */
 182         uint8_t         user:7; /* user specific protocol */
 183         uint8_t         ipi:8;  /* ISO/IEC TR 9557 IPI */
 184         uint32_t        oui:24; /* IEEE 802.1 OUI */
 185         uint32_t        pid:16; /* IEEE 802.1 PID */
 186         uint32_t        noipi;  /* ISO/IEC TR 9557 per frame */
 187 };
 188 .Ed
 189 For the exact rules how matching occures refer to the source code or the
 190 ATM Forum document.
 191 .Pp
 192 Finally the BHLI information element is matched with a
 193 .Bd -literal -offset indent
 194 struct unisve_bhli {
 195         enum unisve_tag tag;
 196         enum uni_bhli   type;   /* type of info */
 197         uint32_t        len;    /* length of info */
 198         uint8_t         info[8];/* info itself */
 199 };
 200 .Ed
 201 .Pp
 202 For each SVE type there is a function that checks whether the SVE is correct
 203 specified.
 204 The functions
 205 .Fn unisve_check_addr ,
 206 .Fn unisve_check_selector ,
 207 .Fn unisve_check_blli_id2 ,
 208 .Fn unisve_check_blli_id3 ,
 209 and
 210 .Fn unisve_check_bhli
 211 return one of the following error codes:
 212 .Bd -literal -offset indent
 213 enum {
 214         UNISVE_OK = 0,
 215         UNISVE_ERROR_BAD_TAG,
 216         UNISVE_ERROR_TYPE_PLAN_CONFLICT,
 217         UNISVE_ERROR_ADDR_SEL_CONFLICT,
 218         UNISVE_ERROR_ADDR_LEN,
 219         UNISVE_ERROR_BAD_ADDR_TYPE,
 220         UNISVE_ERROR_BAD_BHLI_TYPE,
 221         UNISVE_ERROR_BAD_BHLI_LEN,
 222 };
 223 .Ed
 224 .Pp
 225 A code of
 226 .Li UNISVE_OK
 227 means that the SVE has no error.
 228 The function
 229 .Fn unisve_check_sap
 230 checks a complete SAP and returns one of the above codes.
 231 .Pp
 232 There is a definition
 233 .Dv UNISVE_ERRSTR
 234 that evaluates to a comma separated list of strings that can be used
 235 to initializes an array of char pointers to map the error codes into
 236 human readable strings.
 237 .Pp
 238 The ATM Forum document defines the concept of overlaping SAPs.
 239 This basically means, that an incoming SETUP could match more than one SAP
 240 (and more than one application) to receive the SETUP.
 241 For each SVE type there is a function that checks whether two SVEs overlap
 242 and there is a function that checks whether two SAPs overlap.
 243 The functions
 244 .Fn unisve_overlap_addr ,
 245 .Fn unisve_overlap_selector ,
 246 .Fn unisve_overlap_blli_id2 ,
 247 .Fn unisve_overlap_blli_id3 ,
 248 .Fn unisve_overlap_bhli , and
 249 .Fn unisve_overlap_sap
 250 return 1 if the SVEs or SAPs overlap and 0 if they do not.
 251 They assume, that the SAPs are correct.
 252 .Pp
 253 The ATM Forum document specifies a catch-all SAP.
 254 The function
 255 .Fn unisve_is_catchall
 256 returns 1 if the SAP is the catch-all SAP and 0 otherwise.
 257 .Pp
 258 Finally the function
 259 .Fn unisve_match
 260 is used to match a SAP against the information elements from a SETUP message.
 261 It returns 1 if they match and 0 otherwise.
 262 .Sh SEE ALSO
 263 .Xr libunimsg 3
 264 .Sh AUTHORS
 265 .An Hartmut Brandt Aq harti@FreeBSD.org