NetBSD/usr.sbin/pvctxctl/pvctxctl.8

.\" Copyright (C) 1998
.\"	Sony Computer Science Laboratory Inc.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY SONY CSL AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL SONY CSL OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $NetBSD: pvctxctl.8,v 1.5 2002/02/02 01:38:54 wiz Exp $
.\"
.Dd December 29, 1997
.Dt PVCTXCTL 8
.Os
.Sh NAME
.Nm pvctxctl
.Nd display or control ATM PVC transmitter parameters
.Sh SYNOPSIS
.Nm pvctxctl
.Ar interface
.Oo
.Op vpi :
.Ar vci
.Oc
.Nm pvctxctl
.Ar interface
.Op vpi :
.Ar vci
.Op Fl p Ar pcr
.Op Fl b Ar max-bandwidth
.Oo
.Fl j
.Op vpi :
.Ar vci
.Oc
.Op Fl n
.Sh DESCRIPTION
.Nm
displays or controls the shaper parameters of an ATM VC.
When a shaper value is specified,
.Nm
sets a shaper to an ATM VC.
.Nm
works for a PVC sub interface
.Xr pvc 4
as well as a real ATM interface
.Xr en 4 .
.Pp
For a real ATM interface, the specified VC should be assigned
beforehand by
.Xr route 8 .
.Pp
For a sub interface,
.Nm
assigns the specified VC to the sub interface.  If another VC is
already assigned to the sub interface, the old VC is invalidated.
.Pp
Availability of shapers, the number of hardware shaper channels,
and accuracy of shaping are all device dependent.
For example, ENI Midway chip has 8 shaper channels but the driver
reserves one for non-shaping VCs.
.Pp
The options are as follows:
.Bl -tag -width Fl
.It Ar Interface
The
.Ar interface
parameter is a string of the form
.Dq name unit ,
for example,
.Dq en0 .
.It Op vpi: Ar vci
The VC number to which the shaper is assigned.
When the VPI number is omitted, VPI number 0 is
assumed.
For example, to assign a shaper to VPI=0 and
VCI=201, the following forms can be used:
"201", "0xc9", "0:201", "0:0xc9".
.It Fl p Ar pcr
The PCR (Peak Cell Rate) parameter specifies the peak cell rate in
"cells per second".
If PCR value "0" is specified,
no shaper is assigned, which means cells are sent at
full-speed of the link.
If PCR value
.Dq -1
is specified, the corresponding VC
is invalidated.
.It Fl b Ar max-bandwidth
The PCR parameter can be specified also in
.Dq bits per second .
The rate is the rate of AAL5 frame and
the PCR is calculated by the following form:
.Pp
.Dl PCR = max-bandwidth / 8 / 48
.Pp
.Dq K
and
.Dq M
can be used as a short hand of
.Dq 000
and
.Dq 000000
respectively.  For example,
.Dq 45M
means
.Dq 45Mbps
or PCR value
.Dq 117187 .
.It [-j [vpi:]vci]
The join parameter is intended for VP shaping.
The VC shaper channel is shared with the existing VC,
which means the sum of the cell rates never exceeds
the maximum PCR among the shared VCs.
On the other hand, when the shaper channel is not shared,
the sum of the cell rates could be the sum of the PCRs.
.Pp
For example, if two VCs (say 201 and 202) share a
45Mbps VP, use:
.Pp
.Dl # pvctxctl en0 201 -b 45M
.Dl # pvctxctl en0 202 -b 45M -j 201
.It Fl n
This parameter is only for a sub interface.
Use NULL encapsulation instead of LLC/SNAP.
.El
.Sh SEE ALSO
.Xr en 4 ,
.Xr ifconfig 8 ,
.Xr pvcsif 8 ,
.Xr route 8
.Sh BUGS
A real ATM interface and a sub interface require different
sequences to set a shaper.
For example, to assign a 45Mbps shaper to VC 201 (0xc9) of en0:
.Bd -literal -offset indent
# ifconfig en0 10.0.0.1
# route add -iface 10.0.0.2 -link en0:3.0.0.c9
# pvctxctl en0 0xc9 -b 45M
.Ed
.Pp
For a shadow interface,
.Bd -literal -offset indent
# pvcsif en0      			# creates pvc0
# ifconfig pvc0 10.0.0.1 10.0.0.2
# pvctxctl pvc0 201 -b 45M
.Ed