| blob | df4c2e341ef91bcacfb3e1104f0c6c61bb54b706 |
1 .\"
2 .\" Copyright (c) 2001-2003
3 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" SUCH DAMAGE.
26 .\"
27 .\" Author: Hartmut Brandt <harti@FreeBSD.org>
28 .\"
29 .\" $FreeBSD$
30 .\"
31 .\" ng_atm(4) man page
32 .\"
33 .Dd June 24, 2003
34 .Dt NG_ATM 4
35 .Os
36 .Sh NAME
37 .Nm ng_atm
38 .Nd netgraph ATM node type
39 .Sh SYNOPSIS
40 .In sys/types.h
41 .In net/if_atm.h
42 .In netgraph.h
43 .In netgraph/atm/ng_atm.h
44 .Sh DESCRIPTION
45 The
46 .Nm atm
47 netgraph node type allows
48 .Xr natm 4
49 ATM drivers to be connected to the
50 .Xr netgraph 4
51 networking subsystem.
52 When the
53 .Nm
54 module is loaded a node is automatically created for each
55 .Xr natm 4
56 ATM interface.
57 The nodes are named with the same name as the
58 interface.
59 Nodes are also created if a driver for an ATM
60 card is loaded after
61 .Nm
62 was loaded.
63 .Pp
64 The
65 .Nm atm
66 nodes are persistent.
67 They are removed when the interface is removed.
68 .Dv NGM_SHUTDOWN
69 messages are ignored by the node.
70 .Sh HOOKS
71 Four special hooks with fixed names and an unlimited number of hooks with user
72 defined names are supported.
73 Three of the fixed hooks are attached to
74 strategic points in the information flow in the
75 .Xr natm 4
76 system and support only reading.
77 The fourth fixed hook behaves like the other
78 user hooks, but a number of management messages are sent along the hook.
79 The other hooks can be attached to VCIs dynamically by means of
80 control messages to the
81 .Nm atm
82 node and can be written and read.
83 .Pp
84 The four fixed hooks are:
85 .Bl -tag -width ".Va orphans"
86 .It Va input
87 This is a connection to the raw input stream from the network.
88 If this hook is connected, all incoming packets are delivered out to
89 this hook.
90 Note that this redirects ALL input.
91 Neither
92 .Xr natm 4
93 nor the user hooks will see any input if
94 .Va input
95 is connected.
96 An
97 .Vt atm_pseudohdr
98 (see
99 .Xr natm 4 )
100 is prepended to the actual data.
101 .It Va output
102 This is a connection to the raw output stream to the network device.
103 If this hook is connected, all outgoing packets are handed over to
104 the netgraph system and delivered to the hook instead of being delivered
105 to the ATM driver.
106 An
107 .Vt atm_pseudohdr
108 (see
109 .Xr natm 4 )
110 is prepended to the actual data.
111 .It Va orphans
112 This hook receives all packets that are unrecognized, i.e., do not belong to
113 either a
114 .Xr natm 4
115 socket, a
116 .Nm
117 VCI or
118 .Xr natm 4
119 IP.
120 Because ATM is connection oriented and packets are received on a given VCI only
121 when someone initiates this VCI, packets should never be orphaned.
122 There is
123 however one exception: if you use
124 .Xr natm 4
125 IP with LLC/SNAP encapsulation packets with do not have the IP protocol
126 indicated in the packet header are delivered out of this hook.
127 An
128 .Vt atm_pseudohdr
129 (see
130 .Xr natm 4 )
131 is prepended to the actual data send out to the hook.
132 .It Va manage
133 This hook behaves exactly like a normal user hook (see below) except that
134 the node at the other hand will receive management messages.
135 .El
136 .Pp
137 Hooks for dynamically initiated VCIs can have whatever name is allowed by
138 .Xr netgraph 4
139 as long as the name does not collide with one of the three predefined names.
140 .Pp
141 To initiate packet sending an receiving on a dynamic hook one has to issue
142 a
143 .Dv NGM_ATM_CPCS_INIT
144 control message.
145 To terminate sending and receiving one must send a
146 .Dv NGM_ATM_CPCS_TERM
147 message (see
148 .Sx CONTROL MESSAGES ) .
149 The data sent and received on these hooks has no additional
150 headers.
151 .Sh CONTROL MESSAGES
152 This node type supports the generic messages plus the following:
153 .Bl -tag -width 4n
154 .It Dv NGM_ATM_GET_IFNAME
155 Return the name of the interface as a
156 .Dv NUL Ns
157 -terminated string.
158 This is normally the same name as that of the node.
159 .It Dv NGM_ATM_GET_CONFIG
160 Returns a structure defining the configuration of the interface:
161 .Bd -literal
162 struct ng_atm_config {
163 uint32_t pcr; /* peak cell rate */
164 uint32_t maxvpi; /* maximum vpi */
165 uint32_t maxvci; /* maximum vci */
166 uint32_t max_vpcs; /* maximum number of VPCs */
167 uint32_t max_vccs; /* maximum number of VCCs */
168 };
169 .Ed
170 .It Dv NGM_ATM_GET_VCCS
171 Returns the table of open VCCs from the driver.
172 This table consists of
173 a header and a variable sized array of entries, one for each open VCC:
174 .Bd -literal
175 struct atmio_vcctable {
176 uint32_t count; /* number of vccs */
177 struct atmio_vcc vccs[0]; /* array of VCCs */
178 };
179 struct atmio_vcc {
180 uint16_t flags; /* flags */
181 uint16_t vpi; /* VPI */
182 uint16_t vci; /* VCI */
183 uint16_t rmtu; /* Receive maximum CPCS size */
184 uint16_t tmtu; /* Transmit maximum CPCS size */
185 uint8_t aal; /* aal type */
186 uint8_t traffic; /* traffic type */
187 struct atmio_tparam tparam; /* traffic parameters */
188 };
189 struct atmio_tparam {
190 uint32_t pcr; /* 24bit: Peak Cell Rate */
191 uint32_t scr; /* 24bit: VBR Sustainable Cell Rate */
192 uint32_t mbs; /* 24bit: VBR Maximum burst size */
193 uint32_t mcr; /* 24bit: MCR */
194 uint32_t icr; /* 24bit: ABR ICR */
195 uint32_t tbe; /* 24bit: ABR TBE (1...2^24-1) */
196 uint8_t nrm; /* 3bit: ABR Nrm */
197 uint8_t trm; /* 3bit: ABR Trm */
198 uint16_t adtf; /* 10bit: ABR ADTF */
199 uint8_t rif; /* 4bit: ABR RIF */
200 uint8_t rdf; /* 4bit: ABR RDF */
201 uint8_t cdf; /* 3bit: ABR CDF */
202 };
203 .Ed
204 .Pp
205 Note that this is the driver's table, so all VCCs opened via
206 .Xr natm 4
207 sockets and IP are also shown.
208 They can, however, be distinguished by
209 their flags.
210 The
211 .Va flags
212 field contains the following flags:
213 .Pp
214 .Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
215 .It Dv ATM_PH_AAL5
216 use AAL5 instead of AAL0
217 .It Dv ATM_PH_LLCSNAP
218 if AAL5 use LLC SNAP encapsulation
219 .It Dv ATM_FLAG_NG
220 this is a netgraph VCC
221 .It Dv ATM_FLAG_HARP
222 this is a HARP VCC
223 .It Dv ATM_FLAG_NORX
224 transmit only VCC
225 .It Dv ATM_FLAG_NOTX
226 receive only VCC
227 .It Dv ATMIO_FLAG_PVC
228 treat channel as a PVC
229 .El
230 .Pp
231 If the
232 .Dv ATM_FLAG_NG
233 flag is set, then
234 .Va traffic
235 and
236 .Va tparam
237 contain meaningful information.
238 .Pp
239 The
240 .Va aal
241 field
242 contains one of the following values:
243 .Pp
244 .Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
245 .It Dv ATMIO_AAL_0
246 AAL 0 (raw cells)
247 .It Dv ATMIO_AAL_34
248 AAL 3 or AAL 4
249 .It Dv ATMIO_AAL_5
250 AAL 5
251 .It Dv ATMIO_AAL_RAW
252 device specific raw cells
253 .El
254 .Pp
255 The
256 .Va traffic
257 field
258 can have one of the following values (not all drivers support
259 all traffic types however):
260 .Pp
261 .Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
262 .It Dv ATMIO_TRAFFIC_UBR
263 .It Dv ATMIO_TRAFFIC_CBR
264 .It Dv ATMIO_TRAFFIC_ABR
265 .It Dv ATMIO_TRAFFIC_VBR
266 .El
267 .It Dv NGM_ATM_CPCS_INIT
268 Initialize a VCC for sending and receiving.
269 The argument is a structure:
270 .Bd -literal
271 struct ng_atm_cpcs_init {
272 char name[NG_HOOKSIZ];
273 uint32_t flags; /* flags. (if_natmio.h) */
274 uint16_t vci; /* VCI to open */
275 uint16_t vpi; /* VPI to open */
276 uint16_t rmtu; /* receive maximum PDU */
277 uint16_t tmtu; /* transmit maximum PDU */
278 uint8_t aal; /* AAL type (if_natmio.h) */
279 uint8_t traffic; /* traffic type (if_natmio.h) */
280 uint32_t pcr; /* Peak cell rate */
281 uint32_t scr; /* Sustainable cell rate */
282 uint32_t mbs; /* Maximum burst size */
283 uint32_t mcr; /* Minimum cell rate */
284 uint32_t icr; /* ABR: Initial cell rate */
285 uint32_t tbe; /* ABR: Transmit buffer exposure */
286 uint8_t nrm; /* ABR: Nrm */
287 uint8_t trm; /* ABR: Trm */
288 uint16_t adtf; /* ABR: ADTF */
289 uint8_t rif; /* ABR: RIF */
290 uint8_t rdf; /* ABR: RDF */
291 uint8_t cdf; /* ABR: CDF */
292 };
293 .Ed
294 .Pp
295 The
296 .Va name
297 field
298 is the name of the hook for which sending and receiving should be enabled.
299 This hook must already be connected.
300 The
301 .Va vpi
302 and
303 .Va vci
304 fields
305 are the respective VPI and VCI values to use for the ATM cells.
306 They must be
307 within the range, given by the
308 .Va maxvpi
309 and
310 .Va maxvci
311 fields of the
312 .Vt ng_atm_config
313 structure.
314 The
315 .Va flags
316 field
317 contains the flags (see above) and the other fields describe the
318 type of traffic.
319 .It Dv NGM_ATM_CPCS_TERM
320 Stop sending and receiving on the indicated hook.
321 The argument is a
322 .Bd -literal
323 struct ng_atm_cpcs_term {
324 char name[NG_HOOKSIZ];
325 };
326 .Ed
327 .El
328 .Sh MANAGEMENT MESSAGES
329 If the
330 .Va manage
331 hook is connected, certain messages are sent along the hook.
332 They are
333 received by the peer node with a cookie of
334 .Dv NG_ATM_COOKIE .
335 .Bl -tag -width 4n
336 .It Dv NGM_ATM_CARRIER_CHANGE
337 The carrier state of the ATM physical interface has changed.
338 The message has the following structure:
339 .Bd -literal
340 struct ng_atm_carrier_change {
341 uint32_t node;
342 uint32_t state;
343 };
344 .Ed
345 .Pp
346 The
347 .Va node
348 field
349 is the node ID of the ATM node.
350 This can be used by the managing entity
351 (for example
352 .Xr ilmid 8 )
353 to manage several interfaces at the same time through the same node.
354 The
355 .Va state
356 field is 1 if the carrier was detected, and 0 if it was lost.
357 .It Dv NGM_ATM_VCC_CHANGE
358 A permanent VCC has been added, deleted or changed.
359 This is used by
360 .Xr ilmid 8
361 to generate the appropriate ILMI traps.
362 The structure of the message is:
363 .Bd -literal
364 struct ng_atm_vcc_change {
365 uint32_t node;
366 uint16_t vci;
367 uint8_t vpi;
368 uint8_t state;
369 };
370 .Ed
371 Where
372 .Va state
373 is 0 if the PVC was deleted, and 1 if it was added or modified.
374 .El
375 .Sh FLOW CONTROL
376 If the hardware driver supports it, the node can emit flow control messages
377 along a user hook.
378 The format of these messages is described in
379 .In netgraph/ng_message.h .
380 The
381 .Nm atm
382 node may generate
383 .Dv NGM_HIGH_WATER_PASSED
384 and
385 .Dv NGM_LOW_WATER_PASSED
386 messages.
387 The first one indicates that the hardware driver has stopped output
388 on the channel and drops new packets, the second one reports that
389 output was reenabled.
390 Currently, the structures are not filled with
391 information.
392 .Sh SHUTDOWN
393 The nodes are persistent as long as the corresponding interface exists.
394 Upon receipt of a
395 .Dv NGM_SHUTDOWN
396 messages, all hooks are disconnected and the node is reinitialized.
397 All
398 VCCs opened via
399 .Xr netgraph 4
400 are closed.
401 When the ATM interface is unloaded,
402 the node disappears.
403 If the node is compiled with
404 .Dv NGATM_DEBUG
405 there is a sysctl
406 .Va net.graph.atm.allow_shutdown
407 which, when set to a non-zero value, allows the nodes to shut down.
408 Note that this is intended for development only and may lead to kernel
409 panics if set.
410 .Sh SEE ALSO
411 .Xr natm 4 ,
412 .Xr netgraph 4 ,
413 .Xr ng_ether 4 ,
414 .Xr ngctl 8
415 .Sh AUTHORS
416 .An Harti Brandt Aq harti@FreeBSD.org