0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004
0005 ================
0006 Using Linux CAIF
0007 ================
0008
0009
0010 :Copyright: |copy| ST-Ericsson AB 2010
0011
0012 :Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
0013
0014 Start
0015 =====
0016
0017 If you have compiled CAIF for modules do::
0018
0019 $modprobe crc_ccitt
0020 $modprobe caif
0021 $modprobe caif_socket
0022 $modprobe chnl_net
0023
0024
0025 Preparing the setup with a STE modem
0026 ====================================
0027
0028 If you are working on integration of CAIF you should make sure
0029 that the kernel is built with module support.
0030
0031 There are some things that need to be tweaked to get the host TTY correctly
0032 set up to talk to the modem.
0033 Since the CAIF stack is running in the kernel and we want to use the existing
0034 TTY, we are installing our physical serial driver as a line discipline above
0035 the TTY device.
0036
0037 To achieve this we need to install the N_CAIF ldisc from user space.
0038 The benefit is that we can hook up to any TTY.
0039
0040 The use of Start-of-frame-extension (STX) must also be set as
0041 module parameter "ser_use_stx".
0042
0043 Normally Frame Checksum is always used on UART, but this is also provided as a
0044 module parameter "ser_use_fcs".
0045
0046 ::
0047
0048 $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
0049 $ ifconfig caif_ttyS0 up
0050
0051 PLEASE NOTE:
0052 There is a limitation in Android shell.
0053 It only accepts one argument to insmod/modprobe!
0054
0055 Trouble shooting
0056 ================
0057
0058 There are debugfs parameters provided for serial communication.
0059 /sys/kernel/debug/caif_serial/<tty-name>/
0060
0061 * ser_state: Prints the bit-mask status where
0062
0063 - 0x02 means SENDING, this is a transient state.
0064 - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
0065 and is blocking further send operation. Flow OFF has been propagated
0066 to all CAIF Channels using this TTY.
0067
0068 * tty_status: Prints the bit-mask tty status information
0069
0070 - 0x01 - tty->warned is on.
0071 - 0x04 - tty->packed is on.
0072 - 0x08 - tty->flow.tco_stopped is on.
0073 - 0x10 - tty->hw_stopped is on.
0074 - 0x20 - tty->flow.stopped is on.
0075
0076 * last_tx_msg: Binary blob Prints the last transmitted frame.
0077
0078 This can be printed with::
0079
0080 $od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
0081
0082 The first two tx messages sent look like this. Note: The initial
0083 byte 02 is start of frame extension (STX) used for re-syncing
0084 upon errors.
0085
0086 - Enumeration::
0087
0088 0000000 02 05 00 00 03 01 d2 02
0089 | | | | | |
0090 STX(1) | | | |
0091 Length(2)| | |
0092 Control Channel(1)
0093 Command:Enumeration(1)
0094 Link-ID(1)
0095 Checksum(2)
0096
0097 - Channel Setup::
0098
0099 0000000 02 07 00 00 00 21 a1 00 48 df
0100 | | | | | | | |
0101 STX(1) | | | | | |
0102 Length(2)| | | | |
0103 Control Channel(1)
0104 Command:Channel Setup(1)
0105 Channel Type(1)
0106 Priority and Link-ID(1)
0107 Endpoint(1)
0108 Checksum(2)
0109
0110 * last_rx_msg: Prints the last transmitted frame.
0111
0112 The RX messages for LinkSetup look almost identical but they have the
0113 bit 0x20 set in the command bit, and Channel Setup has added one byte
0114 before Checksum containing Channel ID.
0115
0116 NOTE:
0117 Several CAIF Messages might be concatenated. The maximum debug
0118 buffer size is 128 bytes.
0119
0120 Error Scenarios
0121 ===============
0122
0123 - last_tx_msg contains channel setup message and last_rx_msg is empty ->
0124 The host seems to be able to send over the UART, at least the CAIF ldisc get
0125 notified that sending is completed.
0126
0127 - last_tx_msg contains enumeration message and last_rx_msg is empty ->
0128 The host is not able to send the message from UART, the tty has not been
0129 able to complete the transmit operation.
0130
0131 - if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
0132 might be problems transmitting over UART.
0133
0134 E.g. host and modem wiring is not correct you will typically see
0135 tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
0136
0137 You will probably see the enumeration message in last_tx_message
0138 and empty last_rx_message.
