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