link_device.asc from EmStar at Krugle

Show link_device.asc syntax highlighted

The EmStar Link Device
======================
The EmStar Team <emstar-design@cens.ucla.edu>
$Id: link_device.asc,v 1.1 2005/06/14 18:49:37 mlukac Exp $


Link Device
-----------

The Link Device is a logical device composed of a set of sub-devices,
that are organized in a standard way.  Link devices are located under
`/dev/link/<name>/`.  Each Link Device has a unique name, e.g. `udp0`
for an 802.11 link, `mote0` for a mote radio interface, `flood` for a
flood routing module.  Under each name, there is a directory
containing the subdevices that make up the logical Link Device.

Subdevices
~~~~~~~~~~

These subdevices take on standard names, defined in 
link:http://cvs.cens.ucla.edu/lxr/source/emstar/link/include/link_structs.h[link_structs.h].
These subdevices include:

* `data`: a packet device that can send and receive packets to the link.
  Each packet has a header of type `link_pkt_t`.  This header is not generally
  'sent' over the physical link, but rather is only used internally to annotate
  the packet.

* `status`: a status device that reports the current status of the link.
  It reports a structure of type `link_status_t`, including link usage 
  statistics, local link address, and other status information about a
  link.

* `command`: a command interface to control and configure the link.
  Usage information is available by reading from the device.  All links
  support a few common commands, such as setting the local interface ID,
  and many links extend the command set with link-specific commands.
  Passthrough link modules may pass commands that they do not interpret
  down to lower layers.

* `neighbors`: (OPTIONAL) a status device that reports neighborhood information for that
  link.  The neighborhood data is reported in a vector of `neighbor_t` 
  structures (see 
  http://www.lecs.cs.ucla.edu/lxr/source/emstar/link/include/neighbor_structs.h[neighbor_structs.h]), 
  terminated by a structure with a 0 `node_id` field.
  
* `routes`: (OPTIONAL) a status device that reports routing information that relates
  to this routing module.  Routes are reported as a vector of `route_entry_t`
  structures (see
  http://www.lecs.cs.ucla.edu/lxr/source/emstar/routing/include/routing_table.h[routing_table.h]),
  terminated by a structure with a 0 `dst` field.

* `errors`: (OPTIONAL) a packet device that reports any packets received with CRC errors.

Link Structures
~~~~~~~~~~~~~~~

The best and most up-to-date source for detailed information about
these structures is always the source code.  In this section we will
mention only a few of the most important structures and fields.

`link_pkt_t`
^^^^^^^^^^^^

The standard header for data packets over a Link Device is the
`link_pkt_t` structure.  It contains many fields that are common, and
many that apply only to certain types of link interface.  Key fields
include:

* `src.id`, `dst.id`: the address of the source and destination 
  of a packet.  These fields are of type `if_id_t`, but their 
  meaning is specific to specific layers of the stack.  For example
  a link-layer interface such as `mote0` will use a link-layer ID (an
  interface ID), while a network-layer interface such as `flood` will use a
  network-layer ID (a node ID).

* `type`: a one-byte type code that can be used to demultiplex 
  messages.  These type codes are defined in an enum in 
  http://cvs.cens.ucla.edu/lxr/source/emstar/link/include/link_structs.h[link_structs.h].
  `PKT_TYPE_MAC_CTRL` is a special type reserved for control messages that are 
  generated or processed locally by the MAC itself, for example beacon 
  messages, information about peer registration, or 'receipts' that 
  describe the fate of a packet that was sent.

* `ext_type`: a one-byte type code that can be used as a subtype
  for certain messages.  For example, `ext_type` is used to store a
  TinyOS message type when communicating with TinyOS motes.  `ext_type`
  is also used to identify different `MAC_CTRL_TYPE` packets, wh 

* `rcv_time`: a `struct timeval` specifying the approximate time the 
  packet was received, in the local CPU clock.  

* `if_rcv_time`: a 'remote timestamp' structure that may be more 
  accurate when timesync support is in use.

* `max_hops`: a field used by routing modules to define the TTL of a 
  packet, and report the number of hops remaining at reception.

* `rssi`: the RSSI of the received packet, if present.

* `data`: a pointer target to the data following the header.

Note: when sending a packet, in most cases only two fields need be
filled in: `dst.id` and `type`.  All other fields will be filled by
the underlying services.

`link_status_t`
^^^^^^^^^^^^^^^

The `link_status_t` structure defines the data reported in the link
`status` device.  It contains both common fields and fields that may
only apply to certain types of link interface.  Key fields include:

* `root`: the name of the bottom-most link device in the stack.

* `top`: the name of this link device.

* `trace`: the complete sequence of devices in the stack.

* `if_id`: the interface ID for this link.

* `channel_id`: the channel in use by this link, if relevant.

* `MTU`: the maximum payload size in bytes.

* `promisc`: a flag that selects whether the link is in "promiscuous" 
  listening mode.

* `POT`: the transmit power level. 

Link Commands
^^^^^^^^^^^^^

The commands supported by links vary.  See documentation on individual 
link drivers for more details.  Here are a few common commands:

* `power=<x>`: sets the power level (currently only supported by Mote radios)

* `ifid=<x>`: sets the interface ID of the link, if supported.

* `reset`: resets the link driver and/or hardware.


Link Classes
~~~~~~~~~~~~

Link Devices in EmStar are used for many layers of the communications
stack.  Consequently, different link devices need to be identified as
being at an equivalent layer, or different layer.  To support this,
each link can be designated with a "link class".  The link classes
are enumerated in the `/dev/link/classes/` hierarchy.  

Each class assigns a mapping from a small integer to the links in that
class.  The integer is known as a "link index", and is used in the 
`link_multi` interface that can open an entire link class at once.
Several standard link classes are defined, but arbitrary classes can
be specified:

* `none`: an unclassified link

* `link`: a link-layer interface.  These interfaces use link-layer 
  addressing (interface IDs).

* `network`: a network-layer interface.  These interfaces use
  network-layer addressing (node IDs).

As a rule, the emrun macros for link drivers default to class `none`, but
accept a `class=` argument that can define which link class to join.  
Routing modules accept a `uses_class=` argument that specifies a link class 
to open, but open class `link` by default.  So, to hook up a routing module,
simply define whichever interfaces you wish to route through to be class `link`
(e.g. the topmost module in each distinct stack) and start the routing module;
it will open those interfaces you specified as class `link`.


Receipts
~~~~~~~~

Sensor Network applications often need more sophisticated control over
their network interfaces.  One aspect of this is a need to find out 
what happened to a packet that has been sent: 

* When was it actually sent?

* If there is link-layer retransmission, how many times was it transmitted?

* Was it acked by the receiver at the link layer?

To support these possible features of the link layer, EmStar enables
the application to request a reciept for a packet that is sent.  The
link user library includes several functions that are used to request
and process receipts.  

Receipts are requested by calling the `link_receipt_request()` to
annotate the packet header before you send it.  The receipt will be
returned to your application with the same header as sent, except that
the type field will be set to `PKT_TYPE_MAC_CTRL` with the ext_type
`MAC_CTRL_RECEIPT`.  The receipt is also encoded with the PID of the
process that requested it, and can store an application-specific void
pointer.

.NOTE: 
Your while receipts are usually returned when requested, your
application should be robust to a lost receipt due to a bug in the
underlying layer or some other problem.  It's safest to set a timeout
to give up on a missing receipt.

.NOTE: 
Passthrough components should be implemented to pass through 
receipt messages, but of course may not be correctly implemented.
Routing modules are not required to do anything with receipts.
See more files for this project here