.\"	$NetBSD: canconfig.8,v 1.3 2017/05/29 08:46:23 wiz Exp $
.\"
.\" Copyright (c) 2017 Manuel Bouyer.
.\"
.\" 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 THE AUTHOR ``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 THE AUTHOR 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.
.\"
.Dd April 15, 2017
.Dt CANCONFIG 8
.Os
.Sh NAME
.Nm canconfig
.Nd configure CAN network interface parameters
.Sh SYNOPSIS
.Nm
.Fl a
.Nm
.Ar canif
.Nm
.Ar can
.Ar command
.Op Ar args ...
.Sh DESCRIPTION
The
.Nm
utility is used to configure CAN network interface parameters and retrieve
CAN network interface parameters and status from the kernel.
.Ss Timing
The base time unit used to define the network bit rate is the time quanta (tq),
its value is defined by the input clock frequency and the prescaler value
as (1/ freq * prescaler).
.Pp
The network bit time is split in 4 segments:
.Bl -tag -width "phase_seg1" -offset indent -compact
.It sync_seg
fixed to 1 tq
.It prop_seg
.It phase_seg1
.It phase_seg2
.El
The network bit time is (1 + prop_seg + phase_seg1 + phase_seg2), in tq.
The sample point is between phase_seg1 and phase_seg2.
.Pp
The receiver hardware is allowed to shorten prop_seg or phase_seg2 to
resynchronize with the sender.
The swj (Synchronisation Jump Width) parameter
defines by how much the hardware can shorten these segments.
.Pp
Some hardware can use 3 sample points instead of one, and keep the majority as
the final value.
.Ss Options
The options are as follows:
.Bl -tag -width indent
.It Fl a
Display the status of all CAN devices present on the system.
This flag is mutually exclusive with all other sub-commands.
.El
.Pp
All other operations require that a CAN interface be specified.
If a CAN interface is specified with no sub-commands,
the status of that interface is displayed.
.Pp
The following sub-commands are available:
.Bl -tag -width indent
.It Cm up
Start network operations on the interface.
Requires that all timing parameters have been set.
.It Cm down
Stop network operations on the interface.
.It Cm brp Ar value
Set the value of the baud rate prescaler.
.It Cm prop_seg Ar value
Set the number of tq for the propagation segment.
.It Cm phase_seg1 Ar value
Set the number of tq for the phase segment 1.
.It Cm phase_seg2 Ar value
Set the number of tq for the phase segment 2.
.It Cm sjw Ar value
Set the number of tq for the Synchronisation Jump Width.
.It Cm 3samples
Enable triple-sampling.
.It Cm -3samples
Disable triple-sampling.
.It Cm listenonly
Enable listen-only mode.
In this mode the controller is passive, and doesn't send ACKs on the bus.
.It Cm -listenonly
Disable listen-only mode.
.It Cm loopback
Enable loopback mode.
In this mode, the controller doesn't expect ACK from the bus.
.It Cm -loopback
Disable loopback mode.
.El
.\".Sh EXAMPLES
.\"TODO
.Sh SEE ALSO
.Xr ifconfig.if 5 ,
.Xr ifconfig 8
.Sh HISTORY
The
.Nm
utility first appeared in
.Nx 8.0 .
.Sh AUTHORS
This version of the
.Nm
utility was written by
.An Manuel Bouyer .