/share/man/man4/ng_atm.4

  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
 45The
 46.Nm atm
 47netgraph node type allows
 48.Xr natm 4
 49ATM drivers to be connected to the
 50.Xr netgraph 4
 51networking subsystem.
 52When the
 53.Nm
 54module is loaded a node is automatically created for each
 55.Xr natm 4
 56ATM interface.
 57The nodes are named with the same name as the
 58interface.
 59Nodes are also created if a driver for an ATM
 60card is loaded after
 61.Nm
 62was loaded.
 63.Pp
 64The
 65.Nm atm
 66nodes are persistent.
 67They are removed when the interface is removed.
 68.Dv NGM_SHUTDOWN
 69messages are ignored by the node.
 70.Sh HOOKS
 71Four special hooks with fixed names and an unlimited number of hooks with user
 72defined names are supported.
 73Three of the fixed hooks are attached to
 74strategic points in the information flow in the
 75.Xr natm 4
 76system and support only reading.
 77The fourth fixed hook behaves like the other
 78user hooks, but a number of management messages are sent along the hook.
 79The other hooks can be attached to VCIs dynamically by means of
 80control messages to the
 81.Nm atm
 82node and can be written and read.
 83.Pp
 84The four fixed hooks are:
 85.Bl -tag -width ".Va orphans"
 86.It Va input
 87This is a connection to the raw input stream from the network.
 88If this hook is connected, all incoming packets are delivered out to
 89this hook.
 90Note that this redirects ALL input.
 91Neither
 92.Xr natm 4
 93nor the user hooks will see any input if
 94.Va input
 95is connected.
 96An
 97.Vt atm_pseudohdr
 98(see
 99.Xr natm 4 )
100is prepended to the actual data.
101.It Va output
102This is a connection to the raw output stream to the network device.
103If this hook is connected, all outgoing packets are handed over to
104the netgraph system and delivered to the hook instead of being delivered
105to the ATM driver.
106An
107.Vt atm_pseudohdr
108(see
109.Xr natm 4 )
110is prepended to the actual data.
111.It Va orphans
112This hook receives all packets that are unrecognized, i.e., do not belong to
113either a
114.Xr natm 4
115socket, a
116.Nm
117VCI or
118.Xr natm 4
119IP.
120Because ATM is connection oriented and packets are received on a given VCI only
121when someone initiates this VCI, packets should never be orphaned.
122There is
123however one exception: if you use
124.Xr natm 4
125IP with LLC/SNAP encapsulation packets with do not have the IP protocol
126indicated in the packet header are delivered out of this hook.
127An
128.Vt atm_pseudohdr
129(see
130.Xr natm 4 )
131is prepended to the actual data send out to the hook.
132.It Va manage
133This hook behaves exactly like a normal user hook (see below) except that
134the node at the other hand will receive management messages.
135.El
136.Pp
137Hooks for dynamically initiated VCIs can have whatever name is allowed by
138.Xr netgraph 4
139as long as the name does not collide with one of the three predefined names.
140.Pp
141To initiate packet sending and receiving on a dynamic hook, one has to issue
142a
143.Dv NGM_ATM_CPCS_INIT
144control message.
145To terminate sending and receiving one must send a
146.Dv NGM_ATM_CPCS_TERM
147message (see
148.Sx CONTROL MESSAGES ) .
149The data sent and received on these hooks has no additional
150headers.
151.Sh CONTROL MESSAGES
152This node type supports the generic messages plus the following:
153.Bl -tag -width 4n
154.It Dv NGM_ATM_GET_IFNAME
155Return the name of the interface as a
156.Dv NUL Ns
157-terminated string.
158This is normally the same name as that of the node.
159.It Dv NGM_ATM_GET_CONFIG
160Returns a structure defining the configuration of the interface:
161.Bd -literal
162struct 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
171Returns the table of open VCCs from the driver.
172This table consists of
173a header and a variable sized array of entries, one for each open VCC:
174.Bd -literal
175struct atmio_vcctable {
176	uint32_t	count;		/* number of vccs */
177	struct atmio_vcc vccs[0];	/* array of VCCs */
178};
179struct 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};
189struct 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
205Note that this is the driver's table, so all VCCs opened via
206.Xr natm 4
207sockets and IP are also shown.
208They can, however, be distinguished by
209their flags.
210The
211.Va flags
212field contains the following flags:
213.Pp
214.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
215.It Dv ATM_PH_AAL5
216use AAL5 instead of AAL0
217.It Dv ATM_PH_LLCSNAP
218if AAL5 use LLC SNAP encapsulation
219.It Dv ATM_FLAG_NG
220this is a netgraph VCC
221.It Dv ATM_FLAG_HARP
222this is a HARP VCC
223.It Dv ATM_FLAG_NORX
224transmit only VCC
225.It Dv ATM_FLAG_NOTX
226receive only VCC
227.It Dv ATMIO_FLAG_PVC
228treat channel as a PVC
229.El
230.Pp
231If the
232.Dv ATM_FLAG_NG
233flag is set, then
234.Va traffic
235and
236.Va tparam
237contain meaningful information.
238.Pp
239The
240.Va aal
241field
242contains one of the following values:
243.Pp
244.Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
245.It Dv ATMIO_AAL_0
246AAL 0 (raw cells)
247.It Dv ATMIO_AAL_34
248AAL 3 or AAL 4
249.It Dv ATMIO_AAL_5
250AAL 5
251.It Dv ATMIO_AAL_RAW
252device specific raw cells
253.El
254.Pp
255The
256.Va traffic
257field
258can have one of the following values (not all drivers support
259all 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
268Initialize a VCC for sending and receiving.
269The argument is a structure:
270.Bd -literal
271struct 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
295The
296.Va name
297field
298is the name of the hook for which sending and receiving should be enabled.
299This hook must already be connected.
300The
301.Va vpi
302and
303.Va vci
304fields
305are the respective VPI and VCI values to use for the ATM cells.
306They must be
307within the range, given by the
308.Va maxvpi
309and
310.Va maxvci
311fields of the
312.Vt ng_atm_config
313structure.
314The
315.Va flags
316field
317contains the flags (see above) and the other fields describe the
318type of traffic.
319.It Dv NGM_ATM_CPCS_TERM
320Stop sending and receiving on the indicated hook.
321The argument is a
322.Bd -literal
323struct ng_atm_cpcs_term {
324	char		name[NG_HOOKSIZ];
325};
326.Ed
327.El
328.Sh MANAGEMENT MESSAGES
329If the
330.Va manage
331hook is connected, certain messages are sent along the hook.
332They are
333received 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
337The carrier state of the ATM physical interface has changed.
338The message has the following structure:
339.Bd -literal
340struct ng_atm_carrier_change {
341	uint32_t	node;
342	uint32_t	state;
343};
344.Ed
345.Pp
346The
347.Va node
348field
349is the node ID of the ATM node.
350This can be used by the managing entity
351(for example
352.Xr ilmid 8 )
353to manage several interfaces at the same time through the same node.
354The
355.Va state
356field is 1 if the carrier was detected, and 0 if it was lost.
357.It Dv NGM_ATM_VCC_CHANGE
358A permanent VCC has been added, deleted or changed.
359This is used by
360.Xr ilmid 8
361to generate the appropriate ILMI traps.
362The structure of the message is:
363.Bd -literal
364struct ng_atm_vcc_change {
365	uint32_t	node;
366	uint16_t	vci;
367	uint8_t		vpi;
368	uint8_t		state;
369};
370.Ed
371Where
372.Va state
373is 0 if the PVC was deleted, and 1 if it was added or modified.
374.El
375.Sh FLOW CONTROL
376If the hardware driver supports it, the node can emit flow control messages
377along a user hook.
378The format of these messages is described in
379.In netgraph/ng_message.h .
380The
381.Nm atm
382node may generate
383.Dv NGM_HIGH_WATER_PASSED
384and
385.Dv NGM_LOW_WATER_PASSED
386messages.
387The first one indicates that the hardware driver has stopped output
388on the channel and drops new packets, the second one reports that
389output was reenabled.
390Currently, the structures are not filled with
391information.
392.Sh SHUTDOWN
393The nodes are persistent as long as the corresponding interface exists.
394Upon receipt of a
395.Dv NGM_SHUTDOWN
396messages, all hooks are disconnected and the node is reinitialized.
397All
398VCCs opened via
399.Xr netgraph 4
400are closed.
401When the ATM interface is unloaded,
402the node disappears.
403If the node is compiled with
404.Dv NGATM_DEBUG
405there is a sysctl
406.Va net.graph.atm.allow_shutdown
407which, when set to a non-zero value, allows the nodes to shut down.
408Note that this is intended for development only and may lead to kernel
409panics 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