sllin: remove block local variable where function wide one is available.
[linux-lin.git] / sllin / README.txt
1 Intro
2 =====
3 Sllin is TTY discipline enabling you to create LIN Master (and partially
4 LIN Slave) out of your computer.
5 Hardware needed is Hardware UART embedded into the computer + simple
6 voltage level LIN converter.
7
8
9 Compilation
10 ===========
11 To successfully compile sllin, it is necessary to have source code
12 of Linux kernel actually running on the computer.
13
14 To compile, run
15 $ make
16
17
18 First steps
19 ===========
20 To use sllin, it is necessary to set sllin TTY discipline to some
21 existing serial device.
22
23 It is possible to use slightly modified slcan_attach program --
24 particular patch from canutils-patches folder has to be applied.
25
26 After successful compilation and loading of sllin, patching and
27 compiling of slcan_attach, it is possible to run:
28
29 $ sudo slcan_attach -w /dev/ttyS0
30 attached tty /dev/ttyS0 to netdevice sllin0
31 Press any key to detach /dev/ttyS0 ...
32
33 #It is also possible to use ldattach
34 #$ sudo ldattach 25 /dev/ttyS0
35 #(To unattach, kill "ldattach")
36
37 # Run from another terminal
38 $ dmesg
39 [157600.564071] sllin: sllin_kwthread stopped.
40 [157600.572058] netconsole: network logging stopped, interface sllin0 unregistered
41 [157608.437260] sllin: serial line LIN interface driver
42 [157608.437267] sllin: 10 dynamic interface channels.
43 [157608.437271] sllin: Break is generated manually with tiny sleep.
44 [157610.513646] sllin: sllin_open() invoked
45 [157610.519502] sllin: sllin_kwthread started.
46
47 $ ip link show dev sllin0
48 11: sllin0: <NOARP> mtu 16 qdisc noop state DOWN qlen 10
49     link/can
50
51 $ sudo ip link set sllin0 up
52
53 $ ip link show dev sllin0
54 11: sllin0: <NOARP,UP,LOWER_UP> mtu 16 qdisc pfifo_fast state UNKNOWN qlen 10
55     link/can
56
57 # state UNKNOWN in this case is considered as wanted
58
59
60 Real usage
61 ==========
62 Communication with sllin is done by sending different types of CAN
63 frames into it.
64
65 * EFF non-RTR frame:
66   Configuration on internal "frame cache".
67
68 * SFF RTR frame:
69   Send LIN header with LIN ID corresponding to can_id in this
70   particular CAN frame.
71
72 * SFF non-RTR frame:
73   Send LIN header immediately (with LIN ID corresponding to can_id
74   in this particular CAN frame) followed by LIN response containing
75   same data as this particular CAN frame.
76
77
78 Module parameters
79 =================
80 * maxdev
81    -- Optional
82    -- Possible values: unsigned int
83    -- Maximum number of sllin interfaces.
84       When not set, maxdev = 4.
85       When maxdev < 4, maxdev = 4.
86
87 * master
88    -- Optional
89    -- Possible values: 0 or 1
90    -- Sets if LIN interface will be in Master mode (1 = Master, 0 = Slave).
91       When not set, master = 1.
92
93 * baudrate
94    -- Optional
95    -- Possible values: unsigned int
96    -- Baudrate used by LIN interface on LIN bus.
97       When not set, baudrate = LIN_DEFAULT_BAUDRATE (19200).
98
99
100 Examples
101 ========
102 # Some outputs might be slightly modified for more comfortable reading
103
104 $ ls sllin.c
105 sllin.c
106
107 $ make
108 make -C /lib/modules/2.6.36.2-00398-g504e6a6-dirty/build M=/h.../sllin modules
109 make[1]: Entering directory `/h.../kernel/build/glab-2.6.36'
110 make -C /h.../kernel/2.6.36 O=/h.../kernel/build/glab-2.6.36/. modules ARCH=i386
111   CC [M]  /h.../sllin/sllin.o
112   Building modules, stage 2.
113   MODPOST 1 modules
114   LD [M]  /h.../sllin/sllin.ko
115 make[1]: Leaving directory `/h.../kernel/build/glab-2.6.36'
116
117 $ sudo insmod ./sllin.ko
118
119 $ dmesg | tail -3
120 [158268.949289] sllin: serial line LIN interface driver
121 [158268.949296] sllin: 10 dynamic interface channels.
122 [158268.949300] sllin: Break is generated manually with tiny sleep.
123
124 # Run in another terminal
125 $ sudo slcan_attach -w /dev/ttyS0
126 attached tty /dev/ttyS0 to netdevice sllin0
127 Press any key to detach /dev/ttyS0 ...
128
129 $ sudo ip link set sllin0 up
130
131 $ ip link show dev sllin0
132 12: sllin0: <NOARP,UP,LOWER_UP> mtu 16 qdisc pfifo_fast state UNKNOWN qlen 10
133     link/can
134
135 # Run "candump sllin0" in another terminal
136
137
138 # ----- Simple RTR CAN frame -----
139 # Patched version of cangen
140 $ cangen sllin0 -r -I 1 -n 1 -L 0
141
142 # Output from candump
143   sllin0    1  [0] remote request
144   sllin0    1  [2] 00 00
145
146 # First line: RTR sent to sllin0
147 # Second line: Response obtained from LIN bus (there was LIN slave
148 #  device on the LIN bus answering to LIN ID 1with data 0x00 0x00).
149
150
151 # ----- RX_TIMEOUT -----
152 $ cangen sllin0 -r -I 8 -n 1 -L 0
153
154 # LIN_ERR_RX_TIMEOUT flag set -- nobody answered to our LIN header
155 #  or CAN RTR frame
156   sllin0    8  [0] remote request
157   sllin0      2000  [0]
158
159 $ ip -s link show dev sllin0
160 14: sllin0: <NOARP,UP,LOWER_UP> mtu 16 qdisc pfifo_fast state UNKNOWN qlen 10
161     link/can 
162     RX: bytes  packets  errors  dropped overrun mcast   
163     2          4        1       0       0       0      
164     TX: bytes  packets  errors  dropped carrier collsns 
165     0          4        0       0       0       0 
166
167
168
169 # ----- Configure frame cache -----
170 # Configure frame cache to answer on LIN ID = 8
171 $ cangen sllin0 -e -I 0x848 -n 1 -L 2 -D beef
172
173   sllin0       848  [2] BE EF
174
175 # Try RTR CAN frame with ID = 8 again
176 $ cangen sllin0 -r -I 8 -n 1 -L 0
177
178 # Everything went better than expected
179   sllin0    8  [0] remote request
180   sllin0    8  [2] BE EF
181
182
183
184 # ----- non-RTR CAN frame -----
185 $ cangen sllin0 -I 7 -n 1 -L 2 -D f00f
186
187   sllin0    7  [2] F0 0F
188   sllin0    7  [2] F0 0F
189
190
191 # ----- Slave mode -----
192 $ insmod ./sllin.ko master=0
193
194 $ sudo slcan_attach -w /dev/ttyS0
195 attached tty /dev/ttyS0 to netdevice sllin0
196 Press any key to detach /dev/ttyS0 ...
197
198 # run in another terminal
199 $ sudo ip link set sllin0 up
200
201 $ candump -t d sllin0
202  (000.000000)  sllin0    2  [0] remote request
203  (001.003734)  sllin0    1  [0] remote request
204  (000.000017)  sllin0    1  [2] 08 80
205  (000.996027)  sllin0    2  [0] remote request
206  (001.003958)  sllin0    1  [0] remote request
207  (000.000017)  sllin0    1  [2] 08 80
208  (000.996049)  sllin0    2  [0] remote request
209  (001.003930)  sllin0    1  [0] remote request
210  (000.000016)  sllin0    1  [2] 08 80
211  (000.996053)  sllin0    2  [0] remote request
212  (001.003945)  sllin0    1  [0] remote request
213  (000.000017)  sllin0    1  [2] 08 80
214
215 # There is one LIN header without response on the bus (= only RTR CAN frame)
216 # and another LIN header followed by a response (= RTR + non-RTR CAN frame
217 # with the same ID)
218