Documentation/networking/caif/caif.rst

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