1
2 *** This readme will soon be more extensive documentation on the exact
3 *** semantics of the various APIs. For now, it's just a stupid README
4 *** file. -- Jeremy
5
6 LAST UPDATED: 10 April 2000
7
8
9 This directory hierarchy contains software for using the Radiometrix
10 RPC radio. It is designed to be general enough that parts of it,
11 where applicable, can be re-used for other types of radios.
12
13 The software is designed in a more or less layered fashion. The
14 layers are as follows:
15
16 shared/rpc_lowlevel.c: This is a low-level library for managing the
17 parallel pins used to transfer packets between the Linux host and the
18 RPC's packet controller. This file should not directly be used by
19 applications; it is a common building block that is used to create
20 both a user-land library and a kernel-space driver for the RPC (as
21 described below). This file depends on the "parapin" library for the
22 actual control of the parallel port pins.
23
24
25 ************** librpc -- the use-space driver *************************
26
27
28 librpc: This directory contains the stubs for turning the routines in
29 rpc_lowlevel.c into a user-land library for RPC control. By using the
30 include file (include/rpc.h) and the library itself (librpc.a), you
31 can create applications that talk to an RPC connected to a parallel
32 port. Note that only *one* such application can be running at a time,
33 because a mess will ensue if more than one thread is vying for control
34 of a single radio.
35
36 librpc_examples: Example applcations that demonstrate the use of the
37 user-land RPC library described above. Examples are "rpcsend" (sends
38 a packet), "rpctranscieve" (receives), and "rpctorture" (sends
39 continuously).
40
41
42 ************* krpc -- the kernel module *********************************
43
44
45 krpc: Glue to turn the lowlevel RPC library into a kernel module (like
46 librpc, it uses rpc_lowlevel.c) When the kernel-module driver for the
47 RPC is loaded, it registers itself as a character device (major device
48 240). It also registers itself as a network device (rpc0) and can be
49 turned into an IP interface as described below. Only one of these
50 modes can be used at a time (trying to use the network interface while
51 a character device is in use, or vice versa, will return an error of
52 EBUSY or EAGAIN).
53
54 Before you load the kernel module, you must also load the parport and
55 parport_pc modules that are needed (by parapin) to control the
56 parallel port. In particular, if you want to use parallel port
57 interrupts, you have to give parport_pc arguments when you're loading
58 it; i.e.:
59
60 insmod parport
61 insmod parport_pc io=0x378 irq=7
62 insmod krpc
63
64
65 To use the character interace, create a character device file with
66 major number 240, using a statement such as the following:
67
68 mknod /dev/rpc c 240 0 [minor number 0: this creates the standard
69 interface, max of 27 bytes per write]
70
71 mknod /dev/rpcc c 240 1 [minor number 1: this creates the "cooked"
72 interface, which does fragmentation, and
73 allows 16K writes]
74
75 The RPC character device driver implements blocking reads, so to wait
76 for packets, you can just type
77 cat /dev/rpc
78
79 Then, to send a packet containing "hello", on the other side simply do
80 echo hello > /dev/rpc
81
82 Minor number 0 is a raw interface straight to the radio, so it will
83 not accept writes longer than 27 bytes. This is due to the radio
84 hardware's 27 bytes message-size limitation.
85
86 To use the cooked interface that includes fragmentation, allowing
87 you to send longer messages, use minor number 1:
88
89 cat /dev/rpcc (on one side)
90 echo "this is a really long message that requires fragmentation" >
91 /dev/rpcc (on the other side)
92
93 Make sure to set up the receiver before sending; when you start
94 receiving, the queue is cleared of old packets. Just like a socket,
95 you can't receive data that was sent before you were listening for it.
96
97 In many ways, the semantics of the driver are the same as any other
98 character device. For example:
99
100 -- Multiple readers and writers are allowed. Writes are multiplexed
101 correctly. Reads are a little more complicated; like with any
102 other char device, data is only delivered to *one* reader when it
103 comes in, not all of them. The reader that gets the data is
104 undefined (whichever happens to wake up first). These semantics
105 are the same as with any other char device.
106 -- Blocking reads are supported
107 -- Nonblocking reads are supported (if O_NONBLOCK is set using
108 ioctl, and no data is available, a read will return EAGAIN if no
109 data is available)
110 -- The select() and poll() system calls work
111
112 However, there are important differences between this driver and other
113 character devices. In particular, be aware that the sequence of data
114 returned when you issue a read() acts like a datagram interface. All
115 reads will deliver data starting from the beginning of a packet. If a
116 20-byte packet comes in, and you only issue a read for 15 bytes, the
117 remaining 5 bytes are lost forever. The next read does not start
118 where the previous one left off; it gives you the beginning of the
119 next complete packet. Therefore, it is important to issue reads with
120 buffers large enough to consume entire packets.
121
122
123 The radiometrix can also be used as a network device, rpc0. It's a
124 catastrophically slow network interface, but it works. You'd be crazy
125 to try to do anything interactive using it (i.e., telnet), but it
126 might be useful, say, to send simple debugging messages. Just by
127 doing a plain old "ifconfig rpc0 192.168.1.1" on one machine, and
128 "ifconfig rpc0 192.168.1.2" on another, you can have a little ad-hoc
129 network using radiometrix radios that supports IP (including TCP, UDP,
130 ICMP, etc.).
131
132
133 As you've discovered by now, there are many different personalities
134 of the RPC driver:
135 -- char device minor number 0 (raw interface)
136 -- char device minor number 1 (cooked interface)
137 -- network interface
138
139 Only *one* of these personalities may be used at a time. For example,
140 if any process has a raw interface open, an attempt to open cooked
141 interfaces will fail until all raw interfaces have been closed.
142 Similarly, the network interface can not be used at the same time as
143 any flavor of char device.
144
145
146 ********************** deprecated interfaces ***************************
147
148 The following directories are somewhat deprecated (because using the
149 kernel module is better than the user-land library in most cases), but
150 they still exist:
151
152 rpcd: This is a user-land daemon that can multiplex the use of the
153 radio. That is, it is meant to be the only pin-controlling app
154 running on the system. rpcd would never have been written if I'd
155 written the kernel device driver first. In other words, rpcd was just
156 a hack to allow multiple access to the radio -- a job that belongs in
157 the kernel -- without actually doing kernel hacking.
158
159 RPCD has a private message-passin standard that runs between itself
160 and applications that want to send messaes. This message passing is
161 implemented by librpcd_api (described in more detail below). rpcd
162 accepts packets from any number of clients via this IPC channel and
163 writes all clients' packets to the radio without contention. Any
164 packets that it receives are then resent as UDP datagrams to localhost
165 2000. This uses the userland RPC library (just like all the apps in
166 librpc_examples).
167
168 librpcd_api: the rpcd_api library is a library meant to be used by
169 applications that want to send packets to the RPC daemon. It is a
170 small set of interfaces that let apps simply send packets; the library
171 then takes care of transmitting those packets to rpcd. rpcd, in turn,
172 transmits packets out to the radio.
173
174 librpcd_api_examples: These are example applications that send to the
175 radio using the RPCD API library. The rpcd daemon itself must be
176 running for these programs to work correctly.
177
178 The rpcd_shared directory simply contains some files that are shared
179 between librpcd_api and rpcd and is not meant for other apps to use.
180
181
182 *** TO DO ***
183
184 1) Code
185 -- Create support for different flavors of the RPC differentiated
186 by their minor device number. In particular, I think we need:
187 Minor number 0: Raw RPC interface (just like the current driver)
188 Minor number 1: Fragmentation interface so that packets larger
189 than 27 bytes can be transmitted and/or
190 received.
191 Minor number 2: Packets are delivered with additional
192 structures appended with data such as the time
193 of reception of the packet.
194 Minor number 3: Both 1 and 2
195
196 (Note that the numbers are such that these are actually bit
197 flags: 1 == Augment with additinonal data, 2 == Fragmentation.)
198
199 Currently, minor numbers 0 and 1 work; 2 and 3 are unimplemented
200 (as of April 10 2000)
201
202
203 2) Documentation
204
205 EVENTUALLY, this documentation will be more extensive, containing
206 descriptions of the semantics of all the different interfaces, and
207 the semantics of the device driver.
This page was automatically generated by the
LXR engine.
Visit the LXR main site for more
information.
