aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/networking/phonet.txt
diff options
context:
space:
mode:
authorRemi Denis-Courmont <remi.denis-courmont@nokia.com>2008-09-22 23:09:46 -0400
committerDavid S. Miller <davem@davemloft.net>2008-09-22 23:09:46 -0400
commit953f551756a1275d9bfdbb70697323449305161a (patch)
tree0ced6b4e306de39f4315e14334f6be432ebae9ca /Documentation/networking/phonet.txt
parentbe0c52bfed7f7828494fa00060efd5d758e92580 (diff)
Phonet: kernel documentation
Signed-off-by: Rémi Denis-Courmont <remi.denis-courmont@nokia.com> Signed-off-by: David S. Miller <davem@davemloft.net>
Diffstat (limited to 'Documentation/networking/phonet.txt')
-rw-r--r--Documentation/networking/phonet.txt111
1 files changed, 111 insertions, 0 deletions
diff --git a/Documentation/networking/phonet.txt b/Documentation/networking/phonet.txt
new file mode 100644
index 000000000000..f3c72e0ca8d7
--- /dev/null
+++ b/Documentation/networking/phonet.txt
@@ -0,0 +1,111 @@
1Linux 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
24Phonet packet have a common header as follow:
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
36The device ID is split: the 6 higher order bits consitutes the device
37address, while the 2 lower order bits are used for multiplexing, as are
38the 8-bits object identifiers. As such, Phonet can be considered as a
39network layer with 6 bits of address space and 10 bits for transport
40protocol (much like port numbers in IP world).
41
42The modem always has address number zero. Each other device has a its
43own 6-bits address.
44
45
46Link layer
47----------
48
49Phonet links are always point-to-point links. The link layer header
50consists of a single Phonet media type byte. It uniquely identifies the
51link through which the packet is transmitted, from the modem's
52perspective.
53
54Linux Phonet network interfaces use a dedicated link layer type
55(ETH_P_PHONET) which is out of the Ethernet type range. They can only
56send and receive Phonet packets.
57
58Note that Phonet interfaces are not allowed to re-order packets, so
59only the (default) Linux FIFO qdisc should be used with them.
60
61
62Network layer
63-------------
64
65The Phonet socket address family maps the Phonet packet header:
66
67 struct sockaddr_pn {
68 sa_family_t spn_family; /* AF_PHONET */
69 uint8_t spn_obj; /* Object ID */
70 uint8_t spn_dev; /* Device ID */
71 uint8_t spn_resource; /* Resource or function */
72 uint8_t spn_zero[...]; /* Padding */
73 };
74
75The resource field is only used when sending and receiving;
76It is ignored by bind() and getsockname().
77
78
79Low-level datagram protocol
80---------------------------
81
82Applications can send Phonet messages using the Phonet datagram socket
83protocol from the PF_PHONET family. Each socket is bound to one of the
842^10 object IDs available, and can send and receive packets with any
85other peer.
86
87 struct sockaddr_pn addr = { .spn_family = AF_PHONET, };
88 ssize_t len;
89 socklen_t addrlen = sizeof(addr);
90 int fd;
91
92 fd = socket(PF_PHONET, SOCK_DGRAM, 0);
93 bind(fd, (struct sockaddr *)&addr, sizeof(addr));
94 /* ... */
95
96 sendto(fd, msg, msglen, 0, (struct sockaddr *)&addr, sizeof(addr));
97 len = recvfrom(fd, buf, sizeof(buf), 0,
98 (struct sockaddr *)&addr, &addrlen);
99
100This protocol follows the SOCK_DGRAM connection-less semantics.
101However, connect() and getpeername() are not supported, as they did
102not seem useful with Phonet usages (could be added easily).
103
104
105Authors
106-------
107
108Linux Phonet was initially written by Sakari Ailus.
109Other contributors include Mikä Liljeberg, Andras Domokos,
110Carlos Chinea and Rémi Denis-Courmont.
111Copyright (C) 2008 Nokia Corporation.