1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt>
3
4 ============================
5 Linux Phonet protocol family
6 ============================
7
8 Introduction
9 ------------
10
11 Phonet is a packet protocol used by Nokia cell
12 and RPC. With the Linux Phonet socket family,
13 receive and send messages from/to the modem, o
14 device attached to the modem. The modem takes
15
16 Phonet packets can be exchanged through variou
17 depending 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 "FB
23 - the SSI bus with some TI OMAP processors.
24
25
26 Packets format
27 --------------
28
29 Phonet packets have a common header as follows
30
31 struct phonethdr {
32 uint8_t pn_media; /* Media type (link-la
33 uint8_t pn_rdev; /* Receiver device ID
34 uint8_t pn_sdev; /* Sender device ID */
35 uint8_t pn_res; /* Resource ID or func
36 uint16_t pn_length; /* Big-endian message
37 uint8_t pn_robj; /* Receiver object ID
38 uint8_t pn_sobj; /* Sender object ID */
39 };
40
41 On Linux, the link-layer header includes the p
42 The next 7 bytes are part of the network-layer
43
44 The device ID is split: the 6 higher-order bit
45 address, while the 2 lower-order bits are used
46 the 8-bit object identifiers. As such, Phonet
47 network layer with 6 bits of address space and
48 protocol (much like port numbers in IP world).
49
50 The modem always has address number zero. All
51 own 6-bit address.
52
53
54 Link layer
55 ----------
56
57 Phonet links are always point-to-point links.
58 consists of a single Phonet media type byte. I
59 link through which the packet is transmitted,
60 perspective. Each Phonet network device shall
61 type byte as appropriate. For convenience, a c
62 link-layer header operations structure is prov
63 media type according to the network device har
64
65 Linux Phonet network interfaces support a dedi
66 type (ETH_P_PHONET) which is out of the Ethern
67 only send and receive Phonet packets.
68
69 The virtual TUN tunnel device driver can also
70 requires IFF_TUN mode, _without_ the IFF_NO_PI
71 there is no link-layer header, so there is no
72
73 Note that Phonet interfaces are not allowed to
74 only the (default) Linux FIFO qdisc should be
75
76
77 Network layer
78 -------------
79
80 The Phonet socket address family maps the Phon
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
87 uint8_t spn_zero[...]; /* Padding */
88 };
89
90 The resource field is only used when sending a
91 It is ignored by bind() and getsockname().
92
93
94 Low-level datagram protocol
95 ---------------------------
96
97 Applications can send Phonet messages using th
98 protocol from the PF_PHONET family. Each socke
99 2^10 object IDs available, and can send and re
100 other peer.
101
102 ::
103
104 struct sockaddr_pn addr = { .spn_family = AF
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(ad
111 /* ... */
112
113 sendto(fd, msg, msglen, 0, (struct sockaddr
114 len = recvfrom(fd, buf, sizeof(buf), 0,
115 (struct sockaddr *)&addr, &ad
116
117 This protocol follows the SOCK_DGRAM connectio
118 However, connect() and getpeername() are not s
119 not seem useful with Phonet usages (could be a
120
121
122 Resource subscription
123 ---------------------
124
125 A Phonet datagram socket can be subscribed to
126 Phonet resources, as follow::
127
128 uint32_t res = 0xXX;
129 ioctl(fd, SIOCPNADDRESOURCE, &res);
130
131 Subscription is similarly cancelled using the
132 control request, or when the socket is closed.
133
134 Note that no more than one socket can be subsc
135 resource at a time. If not, ioctl() will retur
136
137
138 Phonet Pipe protocol
139 --------------------
140
141 The Phonet Pipe protocol is a simple sequenced
142 with end-to-end congestion control. It uses th
143 socket paradigm. The listening socket is bound
144 ID. Each listening socket can handle up to 255
145 connections, one per accept()'d socket.
146
147 ::
148
149 int lfd, cfd;
150
151 lfd = socket(PF_PHONET, SOCK_SEQPACKET, PN_P
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
166 Connections are traditionally established betw
167 "third party" application. This means that bot
168
169
170 As of Linux kernel version 2.6.39, it is also
171 two endpoints directly, using connect() on the
172 intended to support the newer Nokia Wireless M
173 e.g. the Nokia Slim Modem in the ST-Ericsson U
174
175 struct sockaddr_spn spn;
176 int fd;
177
178 fd = socket(PF_PHONET, SOCK_SEQPACKET, PN_PR
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(
185 /* normal I/O here ... */
186 close(fd);
187
188
189 .. Warning:
190
191 When polling a connected pipe socket for wr
192 intrinsic race condition whereby writabilit
193 polling and the writing system calls. In th
194 block until write becomes possible again, u
195 is enabled.
196
197
198 The pipe protocol provides two socket options
199
200 PNPIPE_ENCAP accepts one integer value (int)
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 vi
207 interface. This requires CAP_NET_ADMIN c
208 support on Nokia modems can use this. No
209 be reliably poll()'d or read() from whil
210
211 PNPIPE_IFINDEX
212 is a read-only integer value. It contain
213 interface index of the network interface
214 or zero if encapsulation is off.
215
216 PNPIPE_HANDLE
217 is a read-only integer value. It contain
218 identifier ("pipe handle") of the pipe.
219 socket descriptors that are already conn
220
221
222 Authors
223 -------
224
225 Linux Phonet was initially written by Sakari A
226
227 Other contributors include Mikä Liljeberg, An
228 Carlos Chinea and Rémi Denis-Courmont.
229
230 Copyright |copy| 2008 Nokia Corporation.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.