.\"	$NetBSD: can.4,v 1.3 2017/05/29 08:41:57 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 May 18, 2017
.Dt CAN 4
.Os
.Sh NAME
.Nm CAN
.Nd CAN Protocol
.Sh SYNOPSIS
.In sys/socket.h
.In netcan/can.h
.Ft int
.Fn socket AF_CAN SOCK_RAW CAN_RAW
.Sh DESCRIPTION
.Nm
is the network layer protocol used on top of CAN bus networks.
At this time only the
.Dv SOCK_RAW
socket type is supported.
This protocol layer is intended to be compatible with the Linux SocketCAN implementation.
.Ss ADDRESSING
A CAN frame consists of a 11 bits (standard frame format) or 29 bits
(extended frame format) identifier, followed by up to 8 data bytes.
The interpretation of the identifier is application-dependent, the CAN
standard itself doesn't define an addressing.
.Pp
The
.Nm
layer uses a 32bits identifier.
The 3 upper bits are used as control flags.
The extended frame format is selected by setting the
.Dv CAN_EFF_FLAG
control bit.
.Pp
The socket address is defined as
.Bd -literal
struct sockaddr_can {
        u_int8_t        can_len;
        sa_family_t     can_family;
        int             can_ifindex;
        union {
                /* transport protocol class address information */
                struct { canid_t rx_id, tx_id; } tp;
                /* reserved for future CAN protocols address information */
        } can_addr;
};
.Ed
For CAN raw sockets, the 32bits identifier is part of the message data.
The can_addr field of the sockaddr structure is not used.
.Ss MESSAGE
Raw CAN sockets use fixed-length messages defined as follow:
.Bd -literal
struct can_frame {
        canid_t can_id; /* ID + EFF/RTR/ERR flags */
        uint8_t can_dlc; /* frame payload length in byte (0 .. CAN_MAX_DLEN) */
        uint8_t __pad;
        uint8_t __res0;
        uint8_t __res1;
        uint8_t data[CAN_MAX_DLEN] __aligned(8);
};
.Ed
The lower 11 bits (for standard frames) or 29 bits (for extended frames) are
used as the on-wire identifier.
The
.Dv CAN_EFF_FLAG
bit is set in can_id for extended frames.
The
.Dv CAN_RTR_FLAG
bit is set in can_id for remote transmission request frames.
.Sh SEE ALSO
.Xr socket 2 ,
.Xr canloop 4 ,
.Xr netintro 4 ,
.Xr canconfig 8 ,
.Pa /usr/include/netcan/can.h
.Pp
.Lk https://en.wikipedia.org/wiki/SocketCAN "SocketCAN - Wikipedia"
.Lk https://www.kernel.org/doc/Documentation/networking/can.txt "Readme file for the Controller Area Network Protocol Family"
.Sh HISTORY
The
.Nm
protocol appeared in
.Nx 8.0 .
.Sh BUGS
.Dv CANFD
and error frames are not implemented.