Using Linux CAIF

CAIF 시작과 STE modem 설정

`.. SPDX-License-Identifier: GPL-2.0`

`.. include:: <isonum.txt>`

Linux CAIF 사용

:Copyright: |copy| ST-Ericsson AB 2010

:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com

시작

CAIF를 module로 compile했다면 다음을 실행합니다.

$modprobe crc_ccitt
$modprobe caif
$modprobe caif_socket
$modprobe chnl_net

STE modem을 사용하는 설정 준비

CAIF 통합 작업을 한다면 kernel이 module 지원을 포함해 build되었는지 확인해야 합니다.

Host TTY가 modem과 올바르게 통신하도록 몇 가지 설정을 조정해야 합니다. CAIF stack은 kernel에서 실행되고 기존 TTY를 사용하려 하므로, 물리 serial driver를 TTY device 위의 line discipline으로 설치합니다.

이를 위해 user space에서 `N_CAIF` ldisc를 설치해야 합니다. 이 방식의 장점은 어떤 TTY에도 연결할 수 있다는 것입니다.

Start-of-frame-extension(STX) 사용 여부도 module parameter `ser_use_stx`로 설정해야 합니다.

일반적으로 UART에서는 Frame Checksum을 항상 사용하지만, 이 설정도 module parameter `ser_use_fcs`로 제공합니다.

$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
$ ifconfig caif_ttyS0 up

주의: Android shell에는 제한이 있어 `insmod`/`modprobe`에 argument 하나만 전달할 수 있습니다.

.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>


================
Using Linux CAIF
================


:Copyright: |copy| ST-Ericsson AB 2010

:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com

Start
=====

If you have compiled CAIF for modules do::

    $modprobe crc_ccitt
    $modprobe caif
    $modprobe caif_socket
    $modprobe chnl_net


Preparing the setup with a STE modem
====================================

If you are working on integration of CAIF you should make sure
that the kernel is built with module support.

There are some things that need to be tweaked to get the host TTY correctly
set up to talk to the modem.
Since the CAIF stack is running in the kernel and we want to use the existing
TTY, we are installing our physical serial driver as a line discipline above
the TTY device.

To achieve this we need to install the N_CAIF ldisc from user space.
The benefit is that we can hook up to any TTY.

The use of Start-of-frame-extension (STX) must also be set as
module parameter "ser_use_stx".

Normally Frame Checksum is always used on UART, but this is also provided as a
module parameter "ser_use_fcs".

::

    $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
    $ ifconfig caif_ttyS0 up

PLEASE NOTE:
                There is a limitation in Android shell.
                It only accepts one argument to insmod/modprobe!

Serial debugfs와 frame 해석

문제 해결

Serial 통신을 진단할 수 있도록 `/sys/kernel/debug/caif_serial/<tty-name>/` 아래에 debugfs parameter가 제공됩니다.

`ser_state`: 다음 bit-mask 상태를 출력합니다.

• `0x02`는 SENDING을 뜻하며 일시적인 상태입니다.
• `0x10`은 FLOW_OFF_SENT를 뜻합니다. 이전 frame이 전송되지 않아 이후 send operation을 막는 상태이며, Flow OFF가 이 TTY를 사용하는 모든 CAIF Channel로 전파되었습니다.

`tty_status`: TTY 상태 정보를 bit-mask로 출력합니다.

• `0x01`: `tty->warned`가 켜져 있습니다.
• `0x04`: `tty->packed`가 켜져 있습니다.
• `0x08`: `tty->flow.tco_stopped`가 켜져 있습니다.
• `0x10`: `tty->hw_stopped`가 켜져 있습니다.
• `0x20`: `tty->flow.stopped`가 켜져 있습니다.

`last_tx_msg`: 마지막으로 전송한 frame을 binary blob으로 출력합니다. 다음 command로 표시할 수 있습니다.

$od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.

처음 전송되는 두 TX message는 다음과 같습니다. 첫 byte `02`는 error 발생 시 다시 동기화하기 위해 쓰는 STX(start of frame extension)입니다.

Enumeration

0000000  02 05 00 00 03 01 d2 02

• `02`: STX(1 byte)
• `05 00`: Length(2 bytes)
• `00`: Control Channel(1 byte)
• `03`: Command: Enumeration(1 byte)
• `01`: Link-ID(1 byte)
• `d2 02`: Checksum(2 bytes)

Channel Setup

0000000  02 07 00 00 00 21 a1 00 48 df

• `02`: STX(1 byte)
• `07 00`: Length(2 bytes)
• `00`: Control Channel(1 byte)
• `00`: Command: Channel Setup(1 byte)
• `21`: Channel Type(1 byte)
• `a1`: Priority and Link-ID(1 byte)
• `00`: Endpoint(1 byte)
• `48 df`: Checksum(2 bytes)

`last_rx_msg`는 마지막으로 수신한 frame을 출력합니다. LinkSetup의 RX message는 거의 같지만 command bit에 `0x20`이 설정되고, Channel Setup은 Checksum 앞에 Channel ID를 담은 byte 하나가 추가됩니다.

주의: CAIF message 여러 개가 연결되어 있을 수 있습니다. Debug buffer의 최대 크기는 128 bytes입니다.

Trouble shooting
================

There are debugfs parameters provided for serial communication.
/sys/kernel/debug/caif_serial/<tty-name>/

* ser_state:   Prints the bit-mask status where

  - 0x02 means SENDING, this is a transient state.
  - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
    and is blocking further send operation. Flow OFF has been propagated
    to all CAIF Channels using this TTY.

* tty_status: Prints the bit-mask tty status information

  - 0x01 - tty->warned is on.
  - 0x04 - tty->packed is on.
  - 0x08 - tty->flow.tco_stopped is on.
  - 0x10 - tty->hw_stopped is on.
  - 0x20 - tty->flow.stopped is on.

* last_tx_msg: Binary blob Prints the last transmitted frame.

  This can be printed with::

        $od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.

  The first two tx messages sent look like this. Note: The initial
  byte 02 is start of frame extension (STX) used for re-syncing
  upon errors.

  - Enumeration::

        0000000  02 05 00 00 03 01 d2 02
                 |  |     |  |  |  |
                 STX(1)   |  |  |  |
                    Length(2)|  |  |
                          Control Channel(1)
                             Command:Enumeration(1)
                                Link-ID(1)
                                    Checksum(2)

  - Channel Setup::

        0000000  02 07 00 00 00 21 a1 00 48 df
                 |  |     |  |  |  |  |  |
                 STX(1)   |  |  |  |  |  |
                    Length(2)|  |  |  |  |
                          Control Channel(1)
                             Command:Channel Setup(1)
                                Channel Type(1)
                                    Priority and Link-ID(1)
                                      Endpoint(1)
                                          Checksum(2)

* last_rx_msg: Prints the last transmitted frame.

  The RX messages for LinkSetup look almost identical but they have the
  bit 0x20 set in the command bit, and Channel Setup has added one byte
  before Checksum containing Channel ID.

  NOTE:
        Several CAIF Messages might be concatenated. The maximum debug
        buffer size is 128 bytes.

오류 시나리오

오류 시나리오

• `last_tx_msg`에 channel setup message가 있고 `last_rx_msg`가 비어 있음: host는 적어도 UART로 보낼 수 있는 것으로 보입니다. CAIF ldisc가 전송 완료 알림을 받았기 때문입니다.
• `last_tx_msg`에 enumeration message가 있고 `last_rx_msg`가 비어 있음: host가 UART에서 message를 보내지 못했습니다. TTY가 transmit operation을 완료하지 못한 상태입니다.
• `/sys/kernel/debug/caif_serial/<tty>/tty_status`가 0이 아니면 UART 전송에 문제가 있을 수 있습니다.

예를 들어 host와 modem 배선이 올바르지 않으면 보통 `tty_status = 0x10 (hw_stopped)`과 `ser_state = 0x10 (FLOW_OFF_SENT)`가 나타납니다.

이 경우 `last_tx_message`에는 enumeration message가 있고 `last_rx_message`는 비어 있을 가능성이 큽니다.

Error Scenarios
===============

- last_tx_msg contains channel setup message and last_rx_msg is empty ->
  The host seems to be able to send over the UART, at least the CAIF ldisc get
  notified that sending is completed.

- last_tx_msg contains enumeration message and last_rx_msg is empty ->
  The host is not able to send the message from UART, the tty has not been
  able to complete the transmit operation.

- if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
  might be problems transmitting over UART.

  E.g. host and modem wiring is not correct you will typically see
  tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).

  You will probably see the enumeration message in last_tx_message
  and empty last_rx_message.