About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / phonet.txt




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:04 EST.

1	Linux Phonet protocol family
2	============================
3	
4	Introduction
5	------------
6	
7	Phonet is a packet protocol used by Nokia cellular modems for both IPC
8	and RPC. With the Linux Phonet socket family, Linux host processes can
9	receive and send messages from/to the modem, or any other external
10	device attached to the modem. The modem takes care of routing.
11	
12	Phonet packets can be exchanged through various hardware connections
13	depending 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	
21	Packets format
22	--------------
23	
24	Phonet 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	
36	On Linux, the link-layer header includes the pn_media byte (see below).
37	The next 7 bytes are part of the network-layer header.
38	
39	The device ID is split: the 6 higher-order bits constitute the device
40	address, while the 2 lower-order bits are used for multiplexing, as are
41	the 8-bit object identifiers. As such, Phonet can be considered as a
42	network layer with 6 bits of address space and 10 bits for transport
43	protocol (much like port numbers in IP world).
44	
45	The modem always has address number zero. All other device have a their
46	own 6-bit address.
47	
48	
49	Link layer
50	----------
51	
52	Phonet links are always point-to-point links. The link layer header
53	consists of a single Phonet media type byte. It uniquely identifies the
54	link through which the packet is transmitted, from the modem's
55	perspective. Each Phonet network device shall prepend and set the media
56	type byte as appropriate. For convenience, a common phonet_header_ops
57	link-layer header operations structure is provided. It sets the
58	media type according to the network device hardware address.
59	
60	Linux Phonet network interfaces support a dedicated link layer packets
61	type (ETH_P_PHONET) which is out of the Ethernet type range. They can
62	only send and receive Phonet packets.
63	
64	The virtual TUN tunnel device driver can also be used for Phonet. This
65	requires IFF_TUN mode, _without_ the IFF_NO_PI flag. In this case,
66	there is no link-layer header, so there is no Phonet media type byte.
67	
68	Note that Phonet interfaces are not allowed to re-order packets, so
69	only the (default) Linux FIFO qdisc should be used with them.
70	
71	
72	Network layer
73	-------------
74	
75	The 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	
85	The resource field is only used when sending and receiving;
86	It is ignored by bind() and getsockname().
87	
88	
89	Low-level datagram protocol
90	---------------------------
91	
92	Applications can send Phonet messages using the Phonet datagram socket
93	protocol from the PF_PHONET family. Each socket is bound to one of the
94	2^10 object IDs available, and can send and receive packets with any
95	other 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	
110	This protocol follows the SOCK_DGRAM connection-less semantics.
111	However, connect() and getpeername() are not supported, as they did
112	not seem useful with Phonet usages (could be added easily).
113	
114	
115	Resource subscription
116	---------------------
117	
118	A Phonet datagram socket can be subscribed to any number of 8-bits
119	Phonet resources, as follow:
120	
121	  uint32_t res = 0xXX;
122	  ioctl(fd, SIOCPNADDRESOURCE, &res);
123	
124	Subscription is similarly cancelled using the SIOCPNDELRESOURCE I/O
125	control request, or when the socket is closed.
126	
127	Note that no more than one socket can be subcribed to any given
128	resource at a time. If not, ioctl() will return EBUSY.
129	
130	
131	Phonet Pipe protocol
132	--------------------
133	
134	The Phonet Pipe protocol is a simple sequenced packets protocol
135	with end-to-end congestion control. It uses the passive listening
136	socket paradigm. The listening socket is bound to an unique free object
137	ID. Each listening socket can handle up to 255 simultaneous
138	connections, 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	
157	Connections are traditionally established between two endpoints by a
158	"third party" application. This means that both endpoints are passive.
159	
160	
161	As of Linux kernel version 2.6.39, it is also possible to connect
162	two endpoints directly, using connect() on the active side. This is
163	intended to support the newer Nokia Wireless Modem API, as found in
164	e.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	
180	WARNING:
181	When polling a connected pipe socket for writability, there is an
182	intrinsic race condition whereby writability might be lost between the
183	polling and the writing system calls. In this case, the socket will
184	block until write becomes possible again, unless non-blocking mode
185	is enabled.
186	
187	
188	The 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	
208	Authors
209	-------
210	
211	Linux Phonet was initially written by Sakari Ailus.
212	Other contributors include Mikä Liljeberg, Andras Domokos,
213	Carlos Chinea and Rémi Denis-Courmont.
214	Copyright (C) 2008 Nokia Corporation.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.