Deleted Added
full compact
ng_atm.4 (131726) ng_atm.4 (131861)
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:

--- 10 unchanged lines hidden (view full) ---

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.\"
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:

--- 10 unchanged lines hidden (view full) ---

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>
27.\" Author: Hartmut Brandt <harti@FreeBSD.org>
28.\"
28.\"
29.\" $FreeBSD: head/share/man/man4/ng_atm.4 131726 2004-07-06 20:43:24Z ru $
29.\" $FreeBSD: head/share/man/man4/ng_atm.4 131861 2004-07-09 07:26:15Z ru $
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
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.Fd #include <net/if_atm.h>
41.Fd #include <netgraph/ng_atm.h>
40.In net/if_atm.h
41.In netgraph/ng_atm.h
42.Sh DESCRIPTION
43The
42.Sh DESCRIPTION
43The
44.Nm
44.Nm atm
45netgraph node type allows
46.Xr natm 4
47ATM drivers to be connected to the
48.Xr netgraph 4
49networking subsystem.
50When the
51.Nm
45netgraph node type allows
46.Xr natm 4
47ATM drivers to be connected to the
48.Xr netgraph 4
49networking subsystem.
50When the
51.Nm
52module is loaded a node is automatically create for each
52module is loaded a node is automatically created for each
53.Xr natm 4
54ATM interface.
55The nodes are named with the same name as the
56interface.
53.Xr natm 4
54ATM interface.
55The nodes are named with the same name as the
56interface.
57Nodes are also created, if a driver for an ATM
57Nodes are also created if a driver for an ATM
58card is loaded after
59.Nm
60was loaded.
61.Pp
58card is loaded after
59.Nm
60was loaded.
61.Pp
62.Nm
62The
63.Nm atm
63nodes are persistent.
64They are removed when the interface is removed.
64nodes are persistent.
65They are removed when the interface is removed.
65SHUTDOWN messages are ignored by the node.
66.Dv NGM_SHUTDOWN
67messages are ignored by the node.
66.Sh HOOKS
67Four special hooks with fixed names and an unlimited number of hooks with user
68defined names are supported.
69Three of the fixed hooks are attached to
70strategic points in the information flow in the
71.Xr natm 4
72system and support only reading.
73The fourth fixed hook behaves like the other
74user hooks, but a number of management messages are sent along the hook.
75The other hooks can be attached to VCIs dynamically by means of
76control messages to the
68.Sh HOOKS
69Four special hooks with fixed names and an unlimited number of hooks with user
70defined names are supported.
71Three of the fixed hooks are attached to
72strategic points in the information flow in the
73.Xr natm 4
74system and support only reading.
75The fourth fixed hook behaves like the other
76user hooks, but a number of management messages are sent along the hook.
77The other hooks can be attached to VCIs dynamically by means of
78control messages to the
77.Nm
79.Nm atm
78node and can be written and read.
79.Pp
80The four fixed hooks are:
80node and can be written and read.
81.Pp
82The four fixed hooks are:
81.Bl -tag -width orphans
82.It Dv input
83.Bl -tag -width ".Va orphans"
84.It Va input
83This is a connection to the raw input stream from the network.
84If this hook is connected, all incoming packets are delivered out to
85this hook.
85This is a connection to the raw input stream from the network.
86If this hook is connected, all incoming packets are delivered out to
87this hook.
86Note, that this redirects ALL input.
88Note that this redirects ALL input.
87Neither
88.Xr natm 4
89nor the user hooks will see any input if
89Neither
90.Xr natm 4
91nor the user hooks will see any input if
90.Dv input
92.Va input
91is connected.
92An
93is connected.
94An
93.Dv atm_pseudohdr
95.Vt atm_pseudohdr
94(see
95.Xr natm 4 )
96is prepended to the actual data.
96(see
97.Xr natm 4 )
98is prepended to the actual data.
97.It Dv output
99.It Va output
98This is a connection to the raw output stream to the network device.
99If this hook is connected, all outgoing packets are handed over to
100the netgraph system and delivered to the hook instead of being delivered
101to the ATM driver.
102An
100This is a connection to the raw output stream to the network device.
101If this hook is connected, all outgoing packets are handed over to
102the netgraph system and delivered to the hook instead of being delivered
103to the ATM driver.
104An
103.Dv atm_pseudohdr
105.Vt atm_pseudohdr
104(see
105.Xr natm 4 )
106is prepended to the actual data.
106(see
107.Xr natm 4 )
108is prepended to the actual data.
107.It Dv orphans
109.It Va orphans
108This hook receives all packets that are unrecognized, i.e., do not belong to
109either a
110.Xr natm 4
111socket, a
112.Nm
113VCI or
114.Xr natm 4
115IP.
116Because ATM is connection oriented and packets are received on a given VCI only
117when someone initiates this VCI, packets should never be orphaned.
118There is
119however one exception: if you use
120.Xr natm 4
110This hook receives all packets that are unrecognized, i.e., do not belong to
111either a
112.Xr natm 4
113socket, a
114.Nm
115VCI or
116.Xr natm 4
117IP.
118Because ATM is connection oriented and packets are received on a given VCI only
119when someone initiates this VCI, packets should never be orphaned.
120There is
121however one exception: if you use
122.Xr natm 4
121IP with LLC/SNAP encapsulation packets with don't have the IP protocol
123IP with LLC/SNAP encapsulation packets with do not have the IP protocol
122indicated in the packet header are delivered out of this hook.
123An
124indicated in the packet header are delivered out of this hook.
125An
124.Dv atm_pseudohdr
126.Vt atm_pseudohdr
125(see
126.Xr natm 4 )
127is prepended to the actual data send out to the hook.
127(see
128.Xr natm 4 )
129is prepended to the actual data send out to the hook.
128.It Dv manage
129This hook behaves exactly like a normal user hook (see below) except, that
130.It Va manage
131This hook behaves exactly like a normal user hook (see below) except that
130the node at the other hand will receive management messages.
131.El
132.Pp
133Hooks for dynamically initiated VCIs can have whatever name is allowed by
134.Xr netgraph 4
135as long as the name does not collide with one of the three predefined names.
136.Pp
137To initiate packet sending an receiving on a dynamic hook one has to issue
138a
139.Dv NGM_ATM_CPCS_INIT
140control message.
141To terminate sending and receiving one must send a
142.Dv NGM_ATM_CPCS_TERM
143message (see
144.Sx CONTROL MESSAGES ) .
132the node at the other hand will receive management messages.
133.El
134.Pp
135Hooks for dynamically initiated VCIs can have whatever name is allowed by
136.Xr netgraph 4
137as long as the name does not collide with one of the three predefined names.
138.Pp
139To initiate packet sending an receiving on a dynamic hook one has to issue
140a
141.Dv NGM_ATM_CPCS_INIT
142control message.
143To terminate sending and receiving one must send a
144.Dv NGM_ATM_CPCS_TERM
145message (see
146.Sx CONTROL MESSAGES ) .
145The data send and received on these hooks has no additional
147The data sent and received on these hooks has no additional
146headers.
147.Sh CONTROL MESSAGES
148This node type supports the generic messages plus the following:
148headers.
149.Sh CONTROL MESSAGES
150This node type supports the generic messages plus the following:
149.Bl -tag -width xxx
151.Bl -tag -width 4n
150.It Dv NGM_ATM_GET_IFNAME
152.It Dv NGM_ATM_GET_IFNAME
151Return the name of the interface as a NUL-terminated string.
153Return the name of the interface as a
154.Dv NUL Ns
155-terminated string.
152This is normally the same name as that of the node.
153.It Dv NGM_ATM_GET_CONFIG
154Returns a structure defining the configuration of the interface:
155.Bd -literal
156struct ng_atm_config {
157 uint32_t pcr; /* peak cell rate */
158 uint32_t maxvpi; /* maximum vpi */
159 uint32_t maxvci; /* maximum vci */
160 uint32_t max_vpcs; /* maximum number of VPCs */
161 uint32_t max_vccs; /* maximum number of VCCs */
162};
163.Ed
164.It Dv NGM_ATM_GET_VCCS
165Returns the table of open VCCs from the driver.
166This table consists of
156This is normally the same name as that of the node.
157.It Dv NGM_ATM_GET_CONFIG
158Returns a structure defining the configuration of the interface:
159.Bd -literal
160struct ng_atm_config {
161 uint32_t pcr; /* peak cell rate */
162 uint32_t maxvpi; /* maximum vpi */
163 uint32_t maxvci; /* maximum vci */
164 uint32_t max_vpcs; /* maximum number of VPCs */
165 uint32_t max_vccs; /* maximum number of VCCs */
166};
167.Ed
168.It Dv NGM_ATM_GET_VCCS
169Returns the table of open VCCs from the driver.
170This table consists of
167a header and a variable sized array of entries, one for each open vcc:
171a header and a variable sized array of entries, one for each open VCC:
168.Bd -literal
169struct atmio_vcctable {
170 uint32_t count; /* number of vccs */
171 struct atmio_vcc vccs[0]; /* array of VCCs */
172};
173struct atmio_vcc {
174 uint16_t flags; /* flags */
175 uint16_t vpi; /* VPI */

--- 15 unchanged lines hidden (view full) ---

191 uint8_t trm; /* 3bit: ABR Trm */
192 uint16_t adtf; /* 10bit: ABR ADTF */
193 uint8_t rif; /* 4bit: ABR RIF */
194 uint8_t rdf; /* 4bit: ABR RDF */
195 uint8_t cdf; /* 3bit: ABR CDF */
196};
197.Ed
198.Pp
172.Bd -literal
173struct atmio_vcctable {
174 uint32_t count; /* number of vccs */
175 struct atmio_vcc vccs[0]; /* array of VCCs */
176};
177struct atmio_vcc {
178 uint16_t flags; /* flags */
179 uint16_t vpi; /* VPI */

--- 15 unchanged lines hidden (view full) ---

195 uint8_t trm; /* 3bit: ABR Trm */
196 uint16_t adtf; /* 10bit: ABR ADTF */
197 uint8_t rif; /* 4bit: ABR RIF */
198 uint8_t rdf; /* 4bit: ABR RDF */
199 uint8_t cdf; /* 3bit: ABR CDF */
200};
201.Ed
202.Pp
199Note, that this is the driver's table, so all VCCs opened via
203Note that this is the driver's table, so all VCCs opened via
200.Xr natm 4
201sockets and IP are also shown.
202They can, however, be distinguished by
203their flags.
204The
204.Xr natm 4
205sockets and IP are also shown.
206They can, however, be distinguished by
207their flags.
208The
205.Dv flags
209.Va flags
206field contains the following flags:
210field contains the following flags:
207.Bl -column ATM_PH_LLCSNAP -offset indent
208.It Dv ATM_PH_AAL5 Ta use AAL5 instead of AAL0
209.It Dv ATM_PH_LLCSNAP Ta if AAL5 use LLC SNAP encapsulation
210.It Dv ATM_FLAG_NG Ta this is a netgraph VCC
211.It Dv ATM_FLAG_HARP Ta this is a HARP VCC
212.It Dv ATM_FLAG_NORX Ta transmit only VCC
213.It Dv ATM_FLAG_NOTX Ta receive only VCC
214.It Dv ATMIO_FLAG_PVC Ta treat channel as a PVC
211.Pp
212.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
213.It Dv ATM_PH_AAL5
214use AAL5 instead of AAL0
215.It Dv ATM_PH_LLCSNAP
216if AAL5 use LLC SNAP encapsulation
217.It Dv ATM_FLAG_NG
218this is a netgraph VCC
219.It Dv ATM_FLAG_HARP
220this is a HARP VCC
221.It Dv ATM_FLAG_NORX
222transmit only VCC
223.It Dv ATM_FLAG_NOTX
224receive only VCC
225.It Dv ATMIO_FLAG_PVC
226treat channel as a PVC
215.El
216.Pp
217If the
218.Dv ATM_FLAG_NG
219flag is set, then
227.El
228.Pp
229If the
230.Dv ATM_FLAG_NG
231flag is set, then
220.Dv traffic
232.Va traffic
221and
233and
222.Dv tparam
234.Va tparam
223contain meaningful information.
224.Pp
235contain meaningful information.
236.Pp
225.Dv aal
237The
238.Va aal
239field
226contains one of the following values:
240contains one of the following values:
227.Bl -column ATM_PH_LLCSNAP -offset indent
228.It Dv ATMIO_AAL_0 Ta AAL 0 (raw cells)
229.It Dv ATMIO_AAL_34 Ta AAL 3 or AAL 4
230.It Dv ATMIO_AAL_5 Ta AAL 5
231.It Dv ATMIO_AAL_RAW Ta device specific raw cells
241.Pp
242.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
243.It Dv ATMIO_AAL_0
244AAL 0 (raw cells)
245.It Dv ATMIO_AAL_34
246AAL 3 or AAL 4
247.It Dv ATMIO_AAL_5
248AAL 5
249.It Dv ATMIO_AAL_RAW
250device specific raw cells
232.El
233.Pp
251.El
252.Pp
234.Dv traffic
253The
254.Va traffic
255field
235can have one of the following values (not all drivers support
236all traffic types however):
256can have one of the following values (not all drivers support
257all traffic types however):
237.Bl -column ATM_PH_LLCSNAP -offset indent
258.Pp
259.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
238.It Dv ATMIO_TRAFFIC_UBR
239.It Dv ATMIO_TRAFFIC_CBR
240.It Dv ATMIO_TRAFFIC_ABR
241.It Dv ATMIO_TRAFFIC_VBR
242.El
243.It Dv NGM_ATM_CPCS_INIT
244Initialize a VCC for sending and receiving.
245The argument is a structure:

--- 17 unchanged lines hidden (view full) ---

263 uint8_t trm; /* ABR: Trm */
264 uint16_t adtf; /* ABR: ADTF */
265 uint8_t rif; /* ABR: RIF */
266 uint8_t rdf; /* ABR: RDF */
267 uint8_t cdf; /* ABR: CDF */
268};
269.Ed
270.Pp
260.It Dv ATMIO_TRAFFIC_UBR
261.It Dv ATMIO_TRAFFIC_CBR
262.It Dv ATMIO_TRAFFIC_ABR
263.It Dv ATMIO_TRAFFIC_VBR
264.El
265.It Dv NGM_ATM_CPCS_INIT
266Initialize a VCC for sending and receiving.
267The argument is a structure:

--- 17 unchanged lines hidden (view full) ---

285 uint8_t trm; /* ABR: Trm */
286 uint16_t adtf; /* ABR: ADTF */
287 uint8_t rif; /* ABR: RIF */
288 uint8_t rdf; /* ABR: RDF */
289 uint8_t cdf; /* ABR: CDF */
290};
291.Ed
292.Pp
271.Dv name
293The
294.Va name
295field
272is the name of the hook for which sending and receiving should be enabled.
273This hook must already be connected.
296is the name of the hook for which sending and receiving should be enabled.
297This hook must already be connected.
274.Dv vpi
298The
299.Va vpi
275and
300and
276.Dv vci
301.Va vci
302fields
277are the respective VPI and VCI values to use for the ATM cells.
278They must be
279within the range, given by the
303are the respective VPI and VCI values to use for the ATM cells.
304They must be
305within the range, given by the
280.Dv maxvpi
306.Va maxvpi
281and
307and
282.Dv maxvci
308.Va maxvci
283fields of the
309fields of the
284.Dv ng_atm_config
310.Vt ng_atm_config
285structure.
311structure.
286.Dv flags
312The
313.Va flags
314field
287contains the flags (see above) and the other fields describe the
288type of traffic.
289.It Dv NGM_ATM_CPCS_TERM
290Stop sending and receiving on the indicated hook.
291The argument is a
292.Bd -literal
293struct ng_atm_cpcs_term {
294 char name[NG_HOOKSIZ];
295};
296.Ed
297.El
298.Sh MANAGEMENT MESSAGES
299If the
315contains the flags (see above) and the other fields describe the
316type of traffic.
317.It Dv NGM_ATM_CPCS_TERM
318Stop sending and receiving on the indicated hook.
319The argument is a
320.Bd -literal
321struct ng_atm_cpcs_term {
322 char name[NG_HOOKSIZ];
323};
324.Ed
325.El
326.Sh MANAGEMENT MESSAGES
327If the
300.Dv manage
301hook is connected certain messages are sent along the hook.
328.Va manage
329hook is connected, certain messages are sent along the hook.
302They are
303received by the peer node with a cookie of
304.Dv NG_ATM_COOKIE .
330They are
331received by the peer node with a cookie of
332.Dv NG_ATM_COOKIE .
305.Bl -tag -width xxx
333.Bl -tag -width 4n
306.It Dv NGM_ATM_CARRIER_CHANGE
307The carrier state of the ATM physical interface has changed.
308The message has the following structure:
309.Bd -literal
310struct ng_atm_carrier_change {
311 uint32_t node;
312 uint32_t state;
313};
314.Ed
315.Pp
334.It Dv NGM_ATM_CARRIER_CHANGE
335The carrier state of the ATM physical interface has changed.
336The message has the following structure:
337.Bd -literal
338struct ng_atm_carrier_change {
339 uint32_t node;
340 uint32_t state;
341};
342.Ed
343.Pp
316.Dv node
317is the node Id of the ATM node.
344The
345.Va node
346field
347is the node ID of the ATM node.
318This can be used by the managing entity
319(for example
320.Xr ilmid 8 )
321to manage several interfaces at the same time through the same node.
348This can be used by the managing entity
349(for example
350.Xr ilmid 8 )
351to manage several interfaces at the same time through the same node.
322.Dv state is 1 if the carrier was detected and 0 if it was lost.
352The
353.Va state
354field is 1 if the carrier was detected, and 0 if it was lost.
323.It Dv NGM_ATM_VCC_CHANGE
324A permanent VCC has been added, deleted or changed.
325This is used by
355.It Dv NGM_ATM_VCC_CHANGE
356A permanent VCC has been added, deleted or changed.
357This is used by
326.Xr ilmid
358.Xr ilmid 8
327to generate the appropriate ILMI traps.
328The structure of the message is:
329.Bd -literal
330struct ng_atm_vcc_change {
331 uint32_t node;
332 uint16_t vci;
333 uint8_t vpi;
334 uint8_t state;
335};
336.Ed
337Where
359to generate the appropriate ILMI traps.
360The structure of the message is:
361.Bd -literal
362struct ng_atm_vcc_change {
363 uint32_t node;
364 uint16_t vci;
365 uint8_t vpi;
366 uint8_t state;
367};
368.Ed
369Where
338.Dv state
339is 0 if the PVC was deleted and 1 if it was added or modified.
370.Va state
371is 0 if the PVC was deleted, and 1 if it was added or modified.
340.El
341.Sh FLOW CONTROL
372.El
373.Sh FLOW CONTROL
342If the hardware driver supports it the node can emit flow control messages
374If the hardware driver supports it, the node can emit flow control messages
343along a user hook.
344The format of these messages is described in
375along a user hook.
376The format of these messages is described in
345.Pa netgraph/ng_message.h .
377.In netgraph/ng_message.h .
346The
378The
347.Nm
379.Nm atm
348node may generate
380node may generate
349.Dv NGM_HIGH_WATER_PASSED and NGM_LOW_WATER_PASSED
381.Dv NGM_HIGH_WATER_PASSED
382and
383.Dv NGM_LOW_WATER_PASSED
350messages.
351The first one indicates that the hardware driver has stopped output
352on the channel and drops new packets, the second one reports that
353output was reenabled.
384messages.
385The first one indicates that the hardware driver has stopped output
386on the channel and drops new packets, the second one reports that
387output was reenabled.
354Currently the structures are not filled with
388Currently, the structures are not filled with
355information.
356.Sh SHUTDOWN
357The nodes are persistent as long as the corresponding interface exists.
358Upon receipt of a
359.Dv NGM_SHUTDOWN
389information.
390.Sh SHUTDOWN
391The nodes are persistent as long as the corresponding interface exists.
392Upon receipt of a
393.Dv NGM_SHUTDOWN
360messages all hooks are disconnected and the node is reinitialized.
394messages, all hooks are disconnected and the node is reinitialized.
361All
395All
362VCCs opened via netgraph are closed.
363When the ATM interface is unloaded
396VCCs opened via
397.Xr netgraph 4
398are closed.
399When the ATM interface is unloaded,
364the node disappears.
365If the node is compiled with
366.Dv NGATM_DEBUG
367there is a sysctl
400the node disappears.
401If the node is compiled with
402.Dv NGATM_DEBUG
403there is a sysctl
368.Cm net.graph.atm.allow_shutdown
369which when set to a non-zero values allows the nodes to shut down.
370Note, that this is intended for development only and may lead to kernel
404.Va net.graph.atm.allow_shutdown
405which, when set to a non-zero value, allows the nodes to shut down.
406Note that this is intended for development only and may lead to kernel
371panics if set.
372.Sh SEE ALSO
373.Xr natm 4 ,
374.Xr netgraph 4 ,
375.Xr ng_ether 4 ,
376.Xr ngctl 8
377.Sh AUTHORS
407panics if set.
408.Sh SEE ALSO
409.Xr natm 4 ,
410.Xr netgraph 4 ,
411.Xr ng_ether 4 ,
412.Xr ngctl 8
413.Sh AUTHORS
378.An Harti Brandt Aq harti@freebsd.org
414.An Harti Brandt Aq harti@FreeBSD.org