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