phonet.rst 7.2 KB

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