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