From 1591c89228352899478b2864af4272fcd021b431 Mon Sep 17 00:00:00 2001 From: hartkopp Date: Fri, 10 Jun 2011 19:08:26 +0000 Subject: [PATCH] documentation: rework chapter numbering & references git-svn-id: svn://svn.berlios.de//socketcan/trunk@1260 030b6a49-0b11-0410-94ab-b0dab22257f2 --- .../Documentation/networking/can/can-bcm.txt | 40 ++++++++--------- .../Documentation/networking/can/can-core.txt | 16 +++---- .../networking/can/can-drivers.txt | 44 +++++++++---------- .../Documentation/networking/can/can-raw.txt | 24 +++++----- .../networking/can/can-sockets.txt | 8 ++-- .../Documentation/networking/can/overview.txt | 2 +- 6 files changed, 67 insertions(+), 67 deletions(-) diff --git a/kernel/2.6/Documentation/networking/can/can-bcm.txt b/kernel/2.6/Documentation/networking/can/can-bcm.txt index 066ce55..56f6d19 100644 --- a/kernel/2.6/Documentation/networking/can/can-bcm.txt +++ b/kernel/2.6/Documentation/networking/can/can-bcm.txt @@ -6,20 +6,20 @@ Part of the documentation for the socketCAN subsystem This file contains: - 1 Broadcast Manager protocol sockets (SOCK_DGRAM) - 1.1 Opening BCM sockets - 1.2 BCM messages (struct bcm_msg_head) - 1.3 TX_SETUP opcode - 1.4 TX_DELETE opcode - 1.5 TX_READ opcode - 1.6 TX_SEND opcode - 1.7 RX_SETUP opcode - 1.8 RX_DELETE opcode - 1.9 RX_READ opcode + B. Broadcast Manager protocol sockets (SOCK_DGRAM) + B.1 Opening BCM sockets + B.2 BCM messages (struct bcm_msg_head) + B.3 TX_SETUP opcode + B.4 TX_DELETE opcode + B.5 TX_READ opcode + B.6 TX_SEND opcode + B.7 RX_SETUP opcode + B.8 RX_DELETE opcode + B.9 RX_READ opcode ============================================================================ -1. Broadcast Manager protocol sockets (SOCK_DGRAM) +B. Broadcast Manager protocol sockets (SOCK_DGRAM) -------------------------------------------------- The Broadcast Manager (BCM) provides functions to send CAN frames @@ -46,7 +46,7 @@ This file contains: - Frequency reduction of messages (throttle function) to the user application - 1.1 Opening BCM sockets + B.1 Opening BCM sockets To use Broadcast-Manager include the file "bcm.h". A socket for Broadcast-Manager is created with: @@ -69,7 +69,7 @@ This file contains: Every single instance of Broadcast-Manager is able to manage any number of filter and/or send requests. - 1.2 BCM messages (struct bcm_msg_head) + B.2 BCM messages (struct bcm_msg_head) All messages from the (user) process to Broadcast-Manager have the same structure. It consists of a message header with the command (opcode), @@ -161,16 +161,16 @@ This file contains: generated when the (cyclic) receive restarts. This will happen even if the user data have not changed - 1.3 TX_SETUP opcode - 1.4 TX_DELETE opcode + B.3 TX_SETUP opcode + B.4 TX_DELETE opcode This opcode will delete the entry for transmission of the CAN frame with the specified can_id CAN identifier. The message length for the command TX_DELETE is sizeof(bcm_msg_head) (only the header). - 1.5 TX_READ opcode - 1.6 TX_SEND opcode - 1.7 RX_SETUP opcode - 1.8 RX_DELETE opcode - 1.9 RX_READ opcode + B.5 TX_READ opcode + B.6 TX_SEND opcode + B.7 RX_SETUP opcode + B.8 RX_DELETE opcode + B.9 RX_READ opcode diff --git a/kernel/2.6/Documentation/networking/can/can-core.txt b/kernel/2.6/Documentation/networking/can/can-core.txt index beaab9e..6a14b8a 100644 --- a/kernel/2.6/Documentation/networking/can/can-core.txt +++ b/kernel/2.6/Documentation/networking/can/can-core.txt @@ -6,14 +6,14 @@ Part of the documentation for the socketCAN subsystem This file contains: - 1 Socket CAN core module - 1.1 can.ko module params - 1.2 procfs content - 1.3 writing own CAN protocol modules + C. Socket CAN core module + C.1 can.ko module params + C.2 procfs content + C.3 writing own CAN protocol modules ============================================================================ -1. Socket CAN core module +C. Socket CAN core module ------------------------- The Socket CAN core module implements the protocol family @@ -21,7 +21,7 @@ This file contains: runtime. The core module provides an interface for CAN protocol modules to subscribe needed CAN IDs (see overview.txt, chapter 3.1). - 1.1 can.ko module params + C.1 can.ko module params - stats_timer: To calculate the Socket CAN core statistics (e.g. current/maximum frames per second) this 1 second timer is @@ -30,7 +30,7 @@ This file contains: - debug: (removed since SocketCAN SVN r546) - 1.2 procfs content + C.2 procfs content As described in overview.txt, chapter 3.1 the Socket CAN core uses several filter lists to deliver received CAN frames to CAN protocol @@ -63,7 +63,7 @@ This file contains: reset_stats - manual statistic reset version - prints the Socket CAN core version and the ABI version - 1.3 writing own CAN protocol modules + C.3 writing own CAN protocol modules To implement a new protocol in the protocol family PF_CAN a new protocol has to be defined in include/linux/can.h . diff --git a/kernel/2.6/Documentation/networking/can/can-drivers.txt b/kernel/2.6/Documentation/networking/can/can-drivers.txt index e666e50..8b69b96 100644 --- a/kernel/2.6/Documentation/networking/can/can-drivers.txt +++ b/kernel/2.6/Documentation/networking/can/can-drivers.txt @@ -6,20 +6,20 @@ Part of the documentation for the socketCAN subsystem This file contains: - 1 CAN network drivers - 1.1 general settings - 1.2 local loopback of sent frames - 1.3 CAN controller hardware filters - 1.4 The virtual CAN driver (vcan) - 1.5 The CAN network device driver interface - 1.5.1 Netlink interface to set/get devices properties - 1.5.2 Setting the CAN bit-timing - 1.5.3 Starting and stopping the CAN network device - 1.6 supported CAN hardware + D. CAN network drivers + D.1 general settings + D.2 local loopback of sent frames + D.3 CAN controller hardware filters + D.4 The virtual CAN driver (vcan) + D.5 The CAN network device driver interface + D.5.1 Netlink interface to set/get devices properties + D.5.2 Setting the CAN bit-timing + D.5.3 Starting and stopping the CAN network device + D.6 supported CAN hardware ============================================================================ -1. CAN network drivers +D. CAN network drivers ---------------------- Writing a CAN network device driver is much easier than writing a @@ -32,7 +32,7 @@ This file contains: See e.g. at Documentation/networking/netdevices.txt . The differences for writing CAN network device driver are described below: - 1.1 general settings + D.1 general settings dev->type = ARPHRD_CAN; /* the netdevice hardware type */ dev->flags = IFF_NOARP; /* CAN has no arp */ @@ -42,9 +42,9 @@ This file contains: The struct can_frame is the payload of each socket buffer in the protocol family PF_CAN. - 1.2 local loopback of sent frames + D.2 local loopback of sent frames - As described in can-sockets.txt (chapter 1.2) the CAN network device + As described in overview.txt (chapter 3.2) the CAN network device driver should support a local loopback functionality similar to the local echo e.g. of tty devices. In this case the driver flag IFF_ECHO has to be set to prevent the PF_CAN core from locally echoing sent @@ -52,7 +52,7 @@ This file contains: dev->flags = (IFF_NOARP | IFF_ECHO); - 1.3 CAN controller hardware filters + D.3 CAN controller hardware filters To reduce the interrupt load on deep embedded systems some CAN controllers support the filtering of CAN IDs or ranges of CAN IDs. @@ -68,7 +68,7 @@ This file contains: @133MHz with four SJA1000 CAN controllers from 2002 under heavy bus load without any problems ... - 1.4 The virtual CAN driver (vcan) + D.4 The virtual CAN driver (vcan) Similar to the network loopback devices, vcan offers a virtual local CAN interface. A full qualified address on CAN consists of @@ -96,7 +96,7 @@ This file contains: - Remove a (virtual CAN) network interface 'vcan42': $ ip link del vcan42 - 1.5 The CAN network device driver interface + D.5 The CAN network device driver interface The CAN network device driver interface provides a generic interface to setup, configure and monitor CAN network devices. The user can then @@ -108,7 +108,7 @@ This file contains: should use. Please have a look to the SJA1000 or MSCAN driver to understand how to use them. The name of the module is can-dev.ko. - 1.5.1 Netlink interface to set/get devices properties + D.5.1 Netlink interface to set/get devices properties The CAN device must be configured via netlink interface. The supported netlink message types are defined and briefly described in @@ -203,7 +203,7 @@ This file contains: bus-off state. RX overrun errors are listed in the "overrun" field of the standard network statistics. - 1.5.2 Setting the CAN bit-timing + D.5.2 Setting the CAN bit-timing The CAN bit-timing parameters can always be defined in a hardware independent format as proposed in the Bosch CAN 2.0 specification @@ -254,12 +254,12 @@ This file contains: $ ip link set canX type can restart Note that a restart will also create a CAN error frame (see also - can-sockets.txt, chapter 1.4). + overview.txt, chapter 3.4). - 1.6 Supported CAN hardware + D.6 Supported CAN hardware Please check the "Kconfig" file in "drivers/net/can" to get an actual list of the support CAN hardware. On the Socket CAN project website - (see overview.txt, chapter 5) there might be further drivers available, + (see overview.txt, chapter 4) there might be further drivers available, also for older kernel versions. diff --git a/kernel/2.6/Documentation/networking/can/can-raw.txt b/kernel/2.6/Documentation/networking/can/can-raw.txt index f1b3f46..b227843 100644 --- a/kernel/2.6/Documentation/networking/can/can-raw.txt +++ b/kernel/2.6/Documentation/networking/can/can-raw.txt @@ -6,16 +6,16 @@ Part of the documentation for the socketCAN subsystem This file contains - 1 RAW protocol sockets with can_filters (SOCK_RAW) - 1.1 RAW socket option CAN_RAW_FILTER - 1.2 RAW socket option CAN_RAW_ERR_FILTER - 1.3 RAW socket option CAN_RAW_LOOPBACK - 1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS - 1.5 RAW socket returned message flags + R. RAW protocol sockets with can_filters (SOCK_RAW) + R.1 RAW socket option CAN_RAW_FILTER + R.2 RAW socket option CAN_RAW_ERR_FILTER + R.3 RAW socket option CAN_RAW_LOOPBACK + R.4 RAW socket option CAN_RAW_RECV_OWN_MSGS + R.5 RAW socket returned message flags ============================================================================ -1. RAW protocol sockets with can_filters (SOCK_RAW) +R. RAW protocol sockets with can_filters (SOCK_RAW) --------------------------------------------------- Using CAN_RAW sockets is extensively comparable to the commonly @@ -32,7 +32,7 @@ This file contains To use the referenced definitions of the socket options for CAN_RAW sockets, include . - 1.1 RAW socket option CAN_RAW_FILTER + R.1 RAW socket option CAN_RAW_FILTER The reception of CAN frames using CAN_RAW sockets can be controlled by defining 0 .. n filters with the CAN_RAW_FILTER socket option. @@ -72,7 +72,7 @@ This file contains having this 'send only' use-case we may remove the receive list in the Kernel to save a little (really a very little!) CPU usage. - 1.2 RAW socket option CAN_RAW_ERR_FILTER + R.2 RAW socket option CAN_RAW_ERR_FILTER As described in overview.txt (chapter 3.4) the CAN interface driver can generate so called Error Frames that can optionally be passed @@ -87,7 +87,7 @@ This file contains setsockopt(s, SOL_CAN_RAW, CAN_RAW_ERR_FILTER, &err_mask, sizeof(err_mask)); - 1.3 RAW socket option CAN_RAW_LOOPBACK + R.3 RAW socket option CAN_RAW_LOOPBACK To meet multi user needs the local loopback is enabled by default (see overview.txt, chapter 3.2, for details). But in some embedded @@ -98,7 +98,7 @@ This file contains setsockopt(s, SOL_CAN_RAW, CAN_RAW_LOOPBACK, &loopback, sizeof(loopback)); - 1.4 RAW socket option CAN_RAW_RECV_OWN_MSGS + R.4 RAW socket option CAN_RAW_RECV_OWN_MSGS When the local loopback is enabled, all the sent CAN frames are looped back to the open CAN sockets that registered for the CAN @@ -113,7 +113,7 @@ This file contains setsockopt(s, SOL_CAN_RAW, CAN_RAW_RECV_OWN_MSGS, &recv_own_msgs, sizeof(recv_own_msgs)); - 1.5 RAW socket returned message flags + R.5 RAW socket returned message flags When using recvmsg() call, the msg->msg_flags may contain following flags: diff --git a/kernel/2.6/Documentation/networking/can/can-sockets.txt b/kernel/2.6/Documentation/networking/can/can-sockets.txt index f07db19..588ce75 100644 --- a/kernel/2.6/Documentation/networking/can/can-sockets.txt +++ b/kernel/2.6/Documentation/networking/can/can-sockets.txt @@ -9,12 +9,12 @@ Part of the documentation for the socketCAN subsystem This file contains: - 1 How to use Socket CAN - 1.1 Timestamps + S. How to use Socket CAN + S.1 Timestamps ============================================================================ -1. How to use Socket CAN +S. How to use Socket CAN ------------------------ Like TCP/IP, you first need to open a socket for communicating over a @@ -146,7 +146,7 @@ This file contains: nbytes = sendto(s, &frame, sizeof(struct can_frame), 0, (struct sockaddr*)&addr, sizeof(addr)); - 1.1 Timestamps + S.1 Timestamps For applications in the CAN environment it is often of interest an accurate timestamp of the instant a message from CAN bus has been received. diff --git a/kernel/2.6/Documentation/networking/can/overview.txt b/kernel/2.6/Documentation/networking/can/overview.txt index 5e33758..cff558f 100644 --- a/kernel/2.6/Documentation/networking/can/overview.txt +++ b/kernel/2.6/Documentation/networking/can/overview.txt @@ -172,7 +172,7 @@ This file contains: data has to be performed right after a successful transmission. If the CAN network interface is not capable of performing the loopback for some reason the SocketCAN core can do this task as a fallback solution. - See can-drivers.txt, chapter 1.2 for details (recommended). + See can-drivers.txt, chapter D.2 for details (recommended). The loopback functionality is enabled by default to reflect standard networking behaviour for CAN applications. Due to some requests from -- 2.39.2