1.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4
5================
6Using Linux CAIF
7================
8
9
10:Copyright: |copy| ST-Ericsson AB 2010
11
12:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
13
14Start
15=====
16
17If you have compiled CAIF for modules do::
18
19    $modprobe crc_ccitt
20    $modprobe caif
21    $modprobe caif_socket
22    $modprobe chnl_net
23
24
25Preparing the setup with a STE modem
26====================================
27
28If you are working on integration of CAIF you should make sure
29that the kernel is built with module support.
30
31There are some things that need to be tweaked to get the host TTY correctly
32set up to talk to the modem.
33Since the CAIF stack is running in the kernel and we want to use the existing
34TTY, we are installing our physical serial driver as a line discipline above
35the TTY device.
36
37To achieve this we need to install the N_CAIF ldisc from user space.
38The benefit is that we can hook up to any TTY.
39
40The use of Start-of-frame-extension (STX) must also be set as
41module parameter "ser_use_stx".
42
43Normally Frame Checksum is always used on UART, but this is also provided as a
44module parameter "ser_use_fcs".
45
46::
47
48    $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
49    $ ifconfig caif_ttyS0 up
50
51PLEASE NOTE:
52		There is a limitation in Android shell.
53		It only accepts one argument to insmod/modprobe!
54
55Trouble shooting
56================
57
58There are debugfs parameters provided for serial communication.
59/sys/kernel/debug/caif_serial/<tty-name>/
60
61* ser_state:   Prints the bit-mask status where
62
63  - 0x02 means SENDING, this is a transient state.
64  - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
65    and is blocking further send operation. Flow OFF has been propagated
66    to all CAIF Channels using this TTY.
67
68* tty_status: Prints the bit-mask tty status information
69
70  - 0x01 - tty->warned is on.
71  - 0x02 - tty->low_latency is on.
72  - 0x04 - tty->packed is on.
73  - 0x08 - tty->flow_stopped is on.
74  - 0x10 - tty->hw_stopped is on.
75  - 0x20 - tty->stopped is on.
76
77* last_tx_msg: Binary blob Prints the last transmitted frame.
78
79  This can be printed with::
80
81	$od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
82
83  The first two tx messages sent look like this. Note: The initial
84  byte 02 is start of frame extension (STX) used for re-syncing
85  upon errors.
86
87  - Enumeration::
88
89        0000000  02 05 00 00 03 01 d2 02
90                 |  |     |  |  |  |
91                 STX(1)   |  |  |  |
92                    Length(2)|  |  |
93                          Control Channel(1)
94                             Command:Enumeration(1)
95                                Link-ID(1)
96                                    Checksum(2)
97
98  - Channel Setup::
99
100        0000000  02 07 00 00 00 21 a1 00 48 df
101                 |  |     |  |  |  |  |  |
102                 STX(1)   |  |  |  |  |  |
103                    Length(2)|  |  |  |  |
104                          Control Channel(1)
105                             Command:Channel Setup(1)
106                                Channel Type(1)
107                                    Priority and Link-ID(1)
108				      Endpoint(1)
109					  Checksum(2)
110
111* last_rx_msg: Prints the last transmitted frame.
112
113  The RX messages for LinkSetup look almost identical but they have the
114  bit 0x20 set in the command bit, and Channel Setup has added one byte
115  before Checksum containing Channel ID.
116
117  NOTE:
118	Several CAIF Messages might be concatenated. The maximum debug
119	buffer size is 128 bytes.
120
121Error Scenarios
122===============
123
124- last_tx_msg contains channel setup message and last_rx_msg is empty ->
125  The host seems to be able to send over the UART, at least the CAIF ldisc get
126  notified that sending is completed.
127
128- last_tx_msg contains enumeration message and last_rx_msg is empty ->
129  The host is not able to send the message from UART, the tty has not been
130  able to complete the transmit operation.
131
132- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
133  might be problems transmitting over UART.
134
135  E.g. host and modem wiring is not correct you will typically see
136  tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
137
138  You will probably see the enumeration message in last_tx_message
139  and empty last_rx_message.
140