linux/Documentation/networking/phonet.txt
<<
>>
Prefs
   1Linux Phonet protocol family
   2============================
   3
   4Introduction
   5------------
   6
   7Phonet is a packet protocol used by Nokia cellular modems for both IPC
   8and RPC. With the Linux Phonet socket family, Linux host processes can
   9receive and send messages from/to the modem, or any other external
  10device attached to the modem. The modem takes care of routing.
  11
  12Phonet packets can be exchanged through various hardware connections
  13depending on the device, such as:
  14  - USB with the CDC Phonet interface,
  15  - infrared,
  16  - Bluetooth,
  17  - an RS232 serial port (with a dedicated "FBUS" line discipline),
  18  - the SSI bus with some TI OMAP processors.
  19
  20
  21Packets format
  22--------------
  23
  24Phonet packets have a common header as follows:
  25
  26  struct phonethdr {
  27    uint8_t  pn_media;  /* Media type (link-layer identifier) */
  28    uint8_t  pn_rdev;   /* Receiver device ID */
  29    uint8_t  pn_sdev;   /* Sender device ID */
  30    uint8_t  pn_res;    /* Resource ID or function */
  31    uint16_t pn_length; /* Big-endian message byte length (minus 6) */
  32    uint8_t  pn_robj;   /* Receiver object ID */
  33    uint8_t  pn_sobj;   /* Sender object ID */
  34  };
  35
  36On Linux, the link-layer header includes the pn_media byte (see below).
  37The next 7 bytes are part of the network-layer header.
  38
  39The device ID is split: the 6 higher-order bits constitute the device
  40address, while the 2 lower-order bits are used for multiplexing, as are
  41the 8-bit object identifiers. As such, Phonet can be considered as a
  42network layer with 6 bits of address space and 10 bits for transport
  43protocol (much like port numbers in IP world).
  44
  45The modem always has address number zero. All other device have a their
  46own 6-bit address.
  47
  48
  49Link layer
  50----------
  51
  52Phonet links are always point-to-point links. The link layer header
  53consists of a single Phonet media type byte. It uniquely identifies the
  54link through which the packet is transmitted, from the modem's
  55perspective. Each Phonet network device shall prepend and set the media
  56type byte as appropriate. For convenience, a common phonet_header_ops
  57link-layer header operations structure is provided. It sets the
  58media type according to the network device hardware address.
  59
  60Linux Phonet network interfaces support a dedicated link layer packets
  61type (ETH_P_PHONET) which is out of the Ethernet type range. They can
  62only send and receive Phonet packets.
  63
  64The virtual TUN tunnel device driver can also be used for Phonet. This
  65requires IFF_TUN mode, _without_ the IFF_NO_PI flag. In this case,
  66there is no link-layer header, so there is no Phonet media type byte.
  67
  68Note that Phonet interfaces are not allowed to re-order packets, so
  69only the (default) Linux FIFO qdisc should be used with them.
  70
  71
  72Network layer
  73-------------
  74
  75The Phonet socket address family maps the Phonet packet header:
  76
  77  struct sockaddr_pn {
  78    sa_family_t spn_family;    /* AF_PHONET */
  79    uint8_t     spn_obj;       /* Object ID */
  80    uint8_t     spn_dev;       /* Device ID */
  81    uint8_t     spn_resource;  /* Resource or function */
  82    uint8_t     spn_zero[...]; /* Padding */
  83  };
  84
  85The resource field is only used when sending and receiving;
  86It is ignored by bind() and getsockname().
  87
  88
  89Low-level datagram protocol
  90---------------------------
  91
  92Applications can send Phonet messages using the Phonet datagram socket
  93protocol from the PF_PHONET family. Each socket is bound to one of the
  942^10 object IDs available, and can send and receive packets with any
  95other peer.
  96
  97  struct sockaddr_pn addr = { .spn_family = AF_PHONET, };
  98  ssize_t len;
  99  socklen_t addrlen = sizeof(addr);
 100  int fd;
 101
 102  fd = socket(PF_PHONET, SOCK_DGRAM, 0);
 103  bind(fd, (struct sockaddr *)&addr, sizeof(addr));
 104  /* ... */
 105
 106  sendto(fd, msg, msglen, 0, (struct sockaddr *)&addr, sizeof(addr));
 107  len = recvfrom(fd, buf, sizeof(buf), 0,
 108                 (struct sockaddr *)&addr, &addrlen);
 109
 110This protocol follows the SOCK_DGRAM connection-less semantics.
 111However, connect() and getpeername() are not supported, as they did
 112not seem useful with Phonet usages (could be added easily).
 113
 114
 115Resource subscription
 116---------------------
 117
 118A Phonet datagram socket can be subscribed to any number of 8-bits
 119Phonet resources, as follow:
 120
 121  uint32_t res = 0xXX;
 122  ioctl(fd, SIOCPNADDRESOURCE, &res);
 123
 124Subscription is similarly cancelled using the SIOCPNDELRESOURCE I/O
 125control request, or when the socket is closed.
 126
 127Note that no more than one socket can be subcribed to any given
 128resource at a time. If not, ioctl() will return EBUSY.
 129
 130
 131Phonet Pipe protocol
 132--------------------
 133
 134The Phonet Pipe protocol is a simple sequenced packets protocol
 135with end-to-end congestion control. It uses the passive listening
 136socket paradigm. The listening socket is bound to an unique free object
 137ID. Each listening socket can handle up to 255 simultaneous
 138connections, one per accept()'d socket.
 139
 140  int lfd, cfd;
 141
 142  lfd = socket(PF_PHONET, SOCK_SEQPACKET, PN_PROTO_PIPE);
 143  listen (lfd, INT_MAX);
 144
 145  /* ... */
 146  cfd = accept(lfd, NULL, NULL);
 147  for (;;)
 148  {
 149    char buf[...];
 150    ssize_t len = read(cfd, buf, sizeof(buf));
 151
 152    /* ... */
 153
 154    write(cfd, msg, msglen);
 155  }
 156
 157Connections are traditionally established between two endpoints by a
 158"third party" application. This means that both endpoints are passive.
 159
 160
 161As of Linux kernel version 2.6.39, it is also possible to connect
 162two endpoints directly, using connect() on the active side. This is
 163intended to support the newer Nokia Wireless Modem API, as found in
 164e.g. the Nokia Slim Modem in the ST-Ericsson U8500 platform:
 165
 166  struct sockaddr_spn spn;
 167  int fd;
 168
 169  fd = socket(PF_PHONET, SOCK_SEQPACKET, PN_PROTO_PIPE);
 170  memset(&spn, 0, sizeof(spn));
 171  spn.spn_family = AF_PHONET;
 172  spn.spn_obj = ...;
 173  spn.spn_dev = ...;
 174  spn.spn_resource = 0xD9;
 175  connect(fd, (struct sockaddr *)&spn, sizeof(spn));
 176  /* normal I/O here ... */
 177  close(fd);
 178
 179
 180WARNING:
 181When polling a connected pipe socket for writability, there is an
 182intrinsic race condition whereby writability might be lost between the
 183polling and the writing system calls. In this case, the socket will
 184block until write becomes possible again, unless non-blocking mode
 185is enabled.
 186
 187
 188The pipe protocol provides two socket options at the SOL_PNPIPE level:
 189
 190  PNPIPE_ENCAP accepts one integer value (int) of:
 191
 192    PNPIPE_ENCAP_NONE: The socket operates normally (default).
 193
 194    PNPIPE_ENCAP_IP: The socket is used as a backend for a virtual IP
 195      interface. This requires CAP_NET_ADMIN capability. GPRS data
 196      support on Nokia modems can use this. Note that the socket cannot
 197      be reliably poll()'d or read() from while in this mode.
 198
 199  PNPIPE_IFINDEX is a read-only integer value. It contains the
 200    interface index of the network interface created by PNPIPE_ENCAP,
 201    or zero if encapsulation is off.
 202
 203  PNPIPE_HANDLE is a read-only integer value. It contains the underlying
 204    identifier ("pipe handle") of the pipe. This is only defined for
 205    socket descriptors that are already connected or being connected.
 206
 207
 208Authors
 209-------
 210
 211Linux Phonet was initially written by Sakari Ailus.
 212Other contributors include Mikä Liljeberg, Andras Domokos,
 213Carlos Chinea and Rémi Denis-Courmont.
 214Copyright (C) 2008 Nokia Corporation.
 215
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.