Linux Phonet protocol family

Nokia modem IPC·RPC와 transport

Phonet은 Nokia cellular modem이 IPC와 RPC에 사용하는 packet protocol입니다. Linux Phonet socket family를 통해 Linux host process는 modem 또는 modem에 연결된 다른 external device와 message를 송수신할 수 있으며 routing은 modem이 담당합니다.

Device에 따라 Phonet packet은 CDC Phonet interface를 사용하는 USB, infrared, Bluetooth, 전용 `FBUS` line discipline을 쓰는 RS232 serial port, 일부 TI OMAP processor의 SSI bus 등 여러 hardware connection으로 교환할 수 있습니다.

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

============================
Linux Phonet protocol family
============================

Introduction
------------

Phonet is a packet protocol used by Nokia cellular modems for both IPC
and RPC. With the Linux Phonet socket family, Linux host processes can
receive and send messages from/to the modem, or any other external
device attached to the modem. The modem takes care of routing.

Phonet packets can be exchanged through various hardware connections
depending on the device, such as:

  - USB with the CDC Phonet interface,
  - infrared,
  - Bluetooth,
  - an RS232 serial port (with a dedicated "FBUS" line discipline),
  - the SSI bus with some TI OMAP processors.

phonethdr와 6+10 bit 주소 구조

모든 Phonet packet에는 공통 `struct phonethdr`가 있습니다. `pn_media`는 media type/link-layer identifier, `pn_rdev`·`pn_sdev`는 receiver·sender device ID, `pn_res`는 resource ID 또는 function, `pn_length`는 6을 뺀 message byte length를 big-endian으로 담습니다. `pn_robj`·`pn_sobj`는 receiver·sender object ID입니다.

Linux에서 link-layer header는 `pn_media` 한 byte를 포함하고 그 뒤 7 byte는 network-layer header입니다.

Device ID의 상위 6 bit는 device address이고 하위 2 bit는 multiplexing에 씁니다. 8-bit object identifier도 multiplexing에 참여하므로 Phonet은 6-bit network address 공간과 IP port number에 비슷한 10-bit transport-protocol 공간을 가진 network layer로 볼 수 있습니다.

Modem address는 항상 0이고 다른 device는 각각 고유한 6-bit address를 갖습니다.

Packets format
--------------

Phonet packets have a common header as follows::

  struct phonethdr {
    uint8_t  pn_media;  /* Media type (link-layer identifier) */
    uint8_t  pn_rdev;   /* Receiver device ID */
    uint8_t  pn_sdev;   /* Sender device ID */
    uint8_t  pn_res;    /* Resource ID or function */
    uint16_t pn_length; /* Big-endian message byte length (minus 6) */
    uint8_t  pn_robj;   /* Receiver object ID */
    uint8_t  pn_sobj;   /* Sender object ID */
  };

On Linux, the link-layer header includes the pn_media byte (see below).
The next 7 bytes are part of the network-layer header.

The device ID is split: the 6 higher-order bits constitute the device
address, while the 2 lower-order bits are used for multiplexing, as are
the 8-bit object identifiers. As such, Phonet can be considered as a
network layer with 6 bits of address space and 10 bits for transport
protocol (much like port numbers in IP world).

The modem always has address number zero. All other device have a their
own 6-bit address.

Point-to-point media byte와 qdisc

Phonet link는 언제나 point-to-point입니다. Link-layer header는 Phonet media-type byte 하나이며 modem 관점에서 packet이 지나가는 link를 고유하게 식별합니다. 각 Phonet network device는 적절한 media type byte를 앞에 붙여 설정해야 합니다.

편의를 위해 공통 `phonet_header_ops` link-layer header operation 구조체가 제공되며 network device hardware address에 따라 media type을 설정합니다.

Linux Phonet interface는 Ethernet type 범위 밖의 전용 link-layer packet type `ETH_P_PHONET`을 지원하고 Phonet packet만 송수신할 수 있습니다.

Virtual TUN tunnel driver도 사용할 수 있지만 `IFF_TUN` mode여야 하고 `IFF_NO_PI` flag는 없어야 합니다. 이 경우 link-layer header 자체가 없으므로 Phonet media-type byte도 없습니다.

Phonet interface는 packet 순서를 바꾸면 안 되므로 기본 Linux FIFO qdisc만 사용해야 합니다.

Link layer
----------

Phonet links are always point-to-point links. The link layer header
consists of a single Phonet media type byte. It uniquely identifies the
link through which the packet is transmitted, from the modem's
perspective. Each Phonet network device shall prepend and set the media
type byte as appropriate. For convenience, a common phonet_header_ops
link-layer header operations structure is provided. It sets the
media type according to the network device hardware address.

Linux Phonet network interfaces support a dedicated link layer packets
type (ETH_P_PHONET) which is out of the Ethernet type range. They can
only send and receive Phonet packets.

The virtual TUN tunnel device driver can also be used for Phonet. This
requires IFF_TUN mode, _without_ the IFF_NO_PI flag. In this case,
there is no link-layer header, so there is no Phonet media type byte.

Note that Phonet interfaces are not allowed to re-order packets, so
only the (default) Linux FIFO qdisc should be used with them.

sockaddr_pn mapping

Phonet socket address family는 packet header를 `struct sockaddr_pn`으로 mapping합니다. `spn_family`는 `AF_PHONET`, `spn_obj`는 object ID, `spn_dev`는 device ID, `spn_resource`는 resource/function이며 `spn_zero`는 padding입니다.

Resource field는 message 송수신 때만 사용되고 `bind()`와 `getsockname()`에서는 무시됩니다.

Network layer
-------------

The Phonet socket address family maps the Phonet packet header::

  struct sockaddr_pn {
    sa_family_t spn_family;    /* AF_PHONET */
    uint8_t     spn_obj;       /* Object ID */
    uint8_t     spn_dev;       /* Device ID */
    uint8_t     spn_resource;  /* Resource or function */
    uint8_t     spn_zero[...]; /* Padding */
  };

The resource field is only used when sending and receiving;
It is ignored by bind() and getsockname().

Connectionless datagram socket

Application은 `PF_PHONET` family의 Phonet datagram socket protocol로 message를 보냅니다. Socket 하나는 사용 가능한 `2^10` object ID 중 하나에 bind되고 다른 어떤 peer와도 packet을 송수신할 수 있습니다.

예제는 `sockaddr_pn`의 family를 `AF_PHONET`으로 설정하고 `socket(PF_PHONET, SOCK_DGRAM, 0)`을 만든 뒤 `bind()`합니다. `sendto()`와 `recvfrom()`은 같은 address 구조체를 사용해 message와 sender address를 교환합니다. 전체 C 호출 순서는 원문에 보존되어 있습니다.

이 protocol은 connectionless `SOCK_DGRAM` semantics를 따릅니다. Phonet 사용 사례에서 유용하지 않다고 판단되어 `connect()`와 `getpeername()`은 지원하지 않지만 필요하면 쉽게 추가할 수 있습니다.

Low-level datagram protocol
---------------------------

Applications can send Phonet messages using the Phonet datagram socket
protocol from the PF_PHONET family. Each socket is bound to one of the
2^10 object IDs available, and can send and receive packets with any
other peer.

::

  struct sockaddr_pn addr = { .spn_family = AF_PHONET, };
  ssize_t len;
  socklen_t addrlen = sizeof(addr);
  int fd;

  fd = socket(PF_PHONET, SOCK_DGRAM, 0);
  bind(fd, (struct sockaddr *)&addr, sizeof(addr));
  /* ... */

  sendto(fd, msg, msglen, 0, (struct sockaddr *)&addr, sizeof(addr));
  len = recvfrom(fd, buf, sizeof(buf), 0,
                 (struct sockaddr *)&addr, &addrlen);

This protocol follows the SOCK_DGRAM connection-less semantics.
However, connect() and getpeername() are not supported, as they did
not seem useful with Phonet usages (could be added easily).

8-bit resource subscription

Phonet datagram socket은 원하는 수의 8-bit Phonet resource를 subscribe할 수 있습니다. `uint32_t res`에 resource를 넣고 `ioctl(fd, SIOCPNADDRESOURCE, &res)`를 호출합니다.

`SIOCPNDELRESOURCE` ioctl로 subscription을 취소할 수 있고 socket을 닫아도 자동 취소됩니다.

특정 resource에는 한 번에 socket 하나만 subscribe할 수 있습니다. 이미 다른 socket이 차지했다면 ioctl은 `EBUSY`를 반환합니다.

Resource subscription
---------------------

A Phonet datagram socket can be subscribed to any number of 8-bits
Phonet resources, as follow::

  uint32_t res = 0xXX;
  ioctl(fd, SIOCPNADDRESOURCE, &res);

Subscription is similarly cancelled using the SIOCPNDELRESOURCE I/O
control request, or when the socket is closed.

Note that no more than one socket can be subscribed to any given
resource at a time. If not, ioctl() will return EBUSY.

Sequenced Pipe protocol과 encapsulation option

Phonet Pipe protocol은 end-to-end congestion control을 갖춘 단순 sequenced-packet protocol이며 passive listening socket 방식을 사용합니다. Listening socket은 고유한 빈 object ID에 bind되고, accept된 socket 하나당 connection 하나로 최대 255개 동시 connection을 처리할 수 있습니다.

예제는 `socket(PF_PHONET, SOCK_SEQPACKET, PN_PROTO_PIPE)`을 만들고 `listen(INT_MAX)`한 뒤 `accept()`합니다. Accepted socket에서는 `read()`와 `write()`로 message를 반복 교환합니다. 전통적으로 두 endpoint 사이 connection은 third-party application이 만들어 주므로 양쪽 endpoint가 모두 passive입니다.

Linux 2.6.39부터 active side에서 `connect()`를 호출해 두 endpoint를 직접 연결할 수도 있습니다. Nokia Slim Modem이 포함된 ST-Ericsson U8500 platform 등 새로운 Nokia Wireless Modem API를 지원하기 위한 기능입니다. 예제는 `sockaddr_pn`에 family, object, device, resource `0xD9`를 채워 connect한 뒤 정상 I/O와 close를 수행합니다.

연결된 pipe socket의 writability를 poll할 때는 poll과 write system call 사이에 writable 상태를 잃을 수 있는 본질적인 race가 있습니다. 이 경우 non-blocking mode가 아니면 write가 다시 가능해질 때까지 socket이 block됩니다.

Pipe protocol은 `SOL_PNPIPE` level에 두 종류의 configurable behavior와 read-only 정보 option을 제공합니다. `PNPIPE_ENCAP_NONE`은 기본 normal socket입니다. `PNPIPE_ENCAP_IP`는 socket을 virtual IP interface의 backend로 사용하며 `CAP_NET_ADMIN`이 필요합니다. Nokia modem의 GPRS data에 사용할 수 있지만 이 mode에서는 socket을 안정적으로 `poll()`하거나 `read()`할 수 없습니다.

`PNPIPE_IFINDEX`는 encapsulation이 만든 network interface의 index를 담는 read-only integer이고 encapsulation이 꺼져 있으면 0입니다. `PNPIPE_HANDLE`은 underlying pipe identifier를 담는 read-only integer이며 이미 연결되었거나 연결 중인 socket descriptor에서만 정의됩니다.

Phonet Pipe protocol
--------------------

The Phonet Pipe protocol is a simple sequenced packets protocol
with end-to-end congestion control. It uses the passive listening
socket paradigm. The listening socket is bound to an unique free object
ID. Each listening socket can handle up to 255 simultaneous
connections, one per accept()'d socket.

::

  int lfd, cfd;

  lfd = socket(PF_PHONET, SOCK_SEQPACKET, PN_PROTO_PIPE);
  listen (lfd, INT_MAX);

  /* ... */
  cfd = accept(lfd, NULL, NULL);
  for (;;)
  {
    char buf[...];
    ssize_t len = read(cfd, buf, sizeof(buf));

    /* ... */

    write(cfd, msg, msglen);
  }

Connections are traditionally established between two endpoints by a
"third party" application. This means that both endpoints are passive.


As of Linux kernel version 2.6.39, it is also possible to connect
two endpoints directly, using connect() on the active side. This is
intended to support the newer Nokia Wireless Modem API, as found in
e.g. the Nokia Slim Modem in the ST-Ericsson U8500 platform::

  struct sockaddr_spn spn;
  int fd;

  fd = socket(PF_PHONET, SOCK_SEQPACKET, PN_PROTO_PIPE);
  memset(&spn, 0, sizeof(spn));
  spn.spn_family = AF_PHONET;
  spn.spn_obj = ...;
  spn.spn_dev = ...;
  spn.spn_resource = 0xD9;
  connect(fd, (struct sockaddr *)&spn, sizeof(spn));
  /* normal I/O here ... */
  close(fd);


.. Warning:

   When polling a connected pipe socket for writability, there is an
   intrinsic race condition whereby writability might be lost between the
   polling and the writing system calls. In this case, the socket will
   block until write becomes possible again, unless non-blocking mode
   is enabled.


The pipe protocol provides two socket options at the SOL_PNPIPE level:

  PNPIPE_ENCAP accepts one integer value (int) of:

    PNPIPE_ENCAP_NONE:
      The socket operates normally (default).

    PNPIPE_ENCAP_IP:
      The socket is used as a backend for a virtual IP
      interface. This requires CAP_NET_ADMIN capability. GPRS data
      support on Nokia modems can use this. Note that the socket cannot
      be reliably poll()'d or read() from while in this mode.

  PNPIPE_IFINDEX
      is a read-only integer value. It contains the
      interface index of the network interface created by PNPIPE_ENCAP,
      or zero if encapsulation is off.

  PNPIPE_HANDLE
      is a read-only integer value. It contains the underlying
      identifier ("pipe handle") of the pipe. This is only defined for
      socket descriptors that are already connected or being connected.

저자와 기여자

Linux Phonet은 Sakari Ailus가 처음 작성했습니다. Mikä Liljeberg, Andras Domokos, Carlos Chinea, Rémi Denis-Courmont도 기여했습니다. Copyright는 2008 Nokia Corporation이며 원문의 `|copy|` 표기를 보존합니다.

Authors
-------

Linux Phonet was initially written by Sakari Ailus.

Other contributors include Mikä Liljeberg, Andras Domokos,
Carlos Chinea and Rémi Denis-Courmont.

Copyright |copy| 2008 Nokia Corporation.