The Character Device

The character device personality of krpc provides simple access to the radio using a convenient file interface.

When krpc is installed, it registers a major device number for the RPC device. By default, the major number is 240 (this number is reserved for local/experimental use in the kernel). To change the major number to something different, use the krpc_major_number module parameter described in Section 3.2. Type cat /proc/devices to see the bindings of major numbers to device drivers.

The driver also has a number of different ``sub-personalities'' that can be selected using the minor number of the device file. Specifically:

Minor Number	Mode Description
0	Raw, direct access to the RPC radio. Messages of more than 27 bytes are not allowed due to the RPC hardware's message-size limitation.
1	Cooked radio interface; implements fragmentation so that larger packets, up to 8K, may be transmitted and/or received.
2	Packets are delivered to applications with the rpc_augmented structure prepended (i.e., before the data). This structure contains meta-data such as the time of reception of the packet. See the header file krpc.h for the definition of this structure.
3	Both 1 and 2.

Remember, only one of these personalities may be used at a time. If one process is reading from /dev/rpc, another process that attempts to open /dev/rpcc will receive EAGAIN.

Creating Device Files

After you decide on a major number to use for krpc, device files using that major number must be created. For example, using major number 240, the following commands would create the appropriate device files:

    mknod /dev/rpc c   240 0 minor number 0: this creates the standard
                              interface, max of 27 bytes per write]

    mknod /dev/rpcc c  240 1 minor number 1: this creates the "cooked"
                              interface, which does fragmentation, and
                              allows 8K writes

    mknod /dev/rpca c  240 2 minor number 2: the "augmented" interface

    mknod /dev/rpcca c 240 3 minor number 3: both 1 and 2

Using the Character Device

The RPC character device driver implements blocking reads, so to wait for incoming packets on a receiver you can just type

    cat /dev/rpc

Then, to send a packet containing ``hello'', on a transmitting side simply type

    echo hello > /dev/rpc

Minor number 0 is a raw interface straight to the radio, so it will not accept writes longer than 27 bytes. This is due to the RPC packet controller's 27 byte message-size limitation.

To use the cooked interface that includes fragmentation, allowing you to send longer messages, use minor number 1:

   cat /dev/rpcc (on one side)
   echo "this is a really long message that requires fragmentation" >
     /dev/rpcc   (on the other side)

Make sure to set up the receiver before sending; when you start receiving, the queue is cleared of old packets. Just like a socket, you can't receive data that was sent before you were listening for it.

In many ways, the semantics of the driver are the same as any other character device. For example:

• Multiple readers and writers are allowed. Writes are multiplexed correctly. Reads are a little more complicated; like with any other char device, data is only delivered to one reader when it comes in, not all of them. The reader that gets the data is undefined (whichever happens to wake up first). These semantics are the same as with any other char device.
• Blocking reads are supported.
• Nonblocking reads are supported; that is, if O_NONBLOCK is set using ioctl, a read will return EAGAIN if no data is immediately available.
• The select() and poll() system calls work

However, there are important differences between this driver and other character devices. In particular, be aware that the sequence of data returned when you issue a read() acts like a datagram interface. All reads will deliver data starting from the beginning of a packet. If a 20-byte packet comes in, and you only issue a read for 15 bytes, the remaining 5 bytes are lost forever. The next read does not start where the previous one left off; it gives you the beginning of the next complete packet. Therefore, it is important to issue reads with buffers large enough to consume entire packets.