blob: 3d127791cb062e51a371ef064254e1546c6111bb [file] [log] [blame]
Remi Denis-Courmont953f5512008-09-22 20:09:46 -07001Linux 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
Rémi Denis-Courmontac2dc8c2008-09-30 02:52:01 -070024Phonet packets have a common header as follows:
Remi Denis-Courmont953f5512008-09-22 20:09:46 -070025
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
Rémi Denis-Courmontac2dc8c2008-09-30 02:52:01 -070036On Linux, the link-layer header includes the pn_media byte (see below).
37The next 7 bytes are part of the network-layer header.
38
Matt LaPlante19f59462009-04-27 15:06:31 +020039The device ID is split: the 6 higher-order bits constitute the device
Rémi Denis-Courmontac2dc8c2008-09-30 02:52:01 -070040address, 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
Remi Denis-Courmont953f5512008-09-22 20:09:46 -070042network layer with 6 bits of address space and 10 bits for transport
43protocol (much like port numbers in IP world).
44
Rémi Denis-Courmontac2dc8c2008-09-30 02:52:01 -070045The modem always has address number zero. All other device have a their
46own 6-bit address.
Remi Denis-Courmont953f5512008-09-22 20:09:46 -070047
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
Rémi Denis-Courmontac2dc8c2008-09-30 02:52:01 -070055perspective. 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.
Remi Denis-Courmont953f5512008-09-22 20:09:46 -070059
Rémi Denis-Courmontac2dc8c2008-09-30 02:52:01 -070060Linux 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.
Remi Denis-Courmont953f5512008-09-22 20:09:46 -070067
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
Rémi Denis-Courmont274a5172010-09-15 12:30:15 +0000115Resource 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
Rémi Denis-Courmont95430c02008-10-05 11:16:36 -0700131Phonet 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
Rémi Denis-Courmont297edb62011-03-08 22:44:12 +0000157Connections 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
Rémi Denis-Courmont95430c02008-10-05 11:16:36 -0700179
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
Randy Macleod3497b2f2008-10-14 13:49:38 -0700184block until write becomes possible again, unless non-blocking mode
185is enabled.
Rémi Denis-Courmont95430c02008-10-05 11:16:36 -0700186
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
Rémi Denis-Courmontacaf7df2011-03-08 22:44:11 +0000203 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
Rémi Denis-Courmont95430c02008-10-05 11:16:36 -0700207
Kumar Sanghvi4d443a02010-09-27 19:35:06 +0000208Phonet Pipe-controller Implementation
209-------------------------------------
210
Rémi Denis-Courmont297edb62011-03-08 22:44:12 +0000211Phonet Pipe-controller is enabled by selecting the CONFIG_PHONET_PIPECTRLR
212Kconfig option.
Kumar Sanghvi4d443a02010-09-27 19:35:06 +0000213
214The implementation adds socket options at SOL_PNPIPE level:
215
Rémi Denis-Courmont03789f22010-10-08 04:02:02 +0000216 PNPIPE_ENABLE accepts one integer value (int). If set to zero, the pipe
217 is disabled. If the value is non-zero, the pipe is enabled. If the pipe
218 is not (yet) connected, ENOTCONN is error is returned.
Kumar Sanghvi4d443a02010-09-27 19:35:06 +0000219
Kumar Sanghvif20ce772010-10-12 20:17:25 +0000220
Remi Denis-Courmont953f5512008-09-22 20:09:46 -0700221Authors
222-------
223
224Linux Phonet was initially written by Sakari Ailus.
225Other contributors include Mikä Liljeberg, Andras Domokos,
226Carlos Chinea and Rémi Denis-Courmont.
227Copyright (C) 2008 Nokia Corporation.