rf.h

定向扩散路由协议

/*

  rf.h

  Header file for the WINSNG 2 Radio API
  
  -------------------------------------------------------------------------
  
  Copyright (c) 2002, Sensoria Corporation.  All rights reserved.
  
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are
  met:
  
  * Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.
  
  * Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.
  
  * Neither the name of the Sensoria Corporation nor the names of
  its contributors may be used to endorse or promote products derived
  from this software without specific prior written permission.
  
  THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS
  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  
*/   

#include <fcntl.h>
#include <errno.h>
#include <unistd.h>
#include <stdarg.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <sys/ioctl.h>
#include <sys/time.h>
#include <inttypes.h>
#include <ctype.h>
#include <rf_ioctl.h>

#ifndef __RF_H__
#define __RF_H__
 
/*Allow linkage to C or C++*/
__BEGIN_DECLS


/*
 *  RF device naming helper functions and constants.
 *
 *  Radio devices are located in /dev/rf/[01]/.  Each rf interface
 *  has several device files used for different purposes.  These
 *  "variant" types and functions are used to simplify naming and 
 *  opening the appropriate files.
 *
 *  Once a file descriptor has been acquired, it can be used with 
 *  the relevant API calls.
 *
 *  RAW is a raw packet interface, with a limited MTU
 *  COOKED is a fragmentation interface, with a 64K MTU
 *  COMMAND is a command interface for controlling the radio
 *  NEIGHBORS is an interface that provides a list of the
 *            current directly connected peers
 */

typedef enum {
  RF_RAW,                 /* /dev/rf/0/link              */
  RF_COOKED,              /* /dev/rf/0/flink             */
  RF_STATUS,              /* /dev/rf/0/status            */
  RF_COMMAND,             /* /dev/rf/0/command           */
  RF_CONNECT_NOTIFIER,    /* /dev/rf/0/connect           */
  RF_HANDLE_MAP,          /* /dev/rf/0/handle_map        */
  RF_NEIGHBORS,           /* /dev/rf/0/neighbors         */
  RF_NEIGHBORS_CONTROL    /* /dev/rf/0/neighbors_control */
} radio_variant_t;

/* gets a radio-related device name */
char *rf_get_dev_name(int dev_index, radio_variant_t variant);

/* opens and returns a radio-related file descriptor */
int rf_get_dev_fd(int dev_index, radio_variant_t variant);

 
/*
 *  Packet formats and related types and constants
 *
 *  The rf_pkt structure defines a header used when sending or
 *  receiving packets from an RF interface.
 *
 *  The RAW device has a small maximum MTU dependent on the radio settings.
 *  The COOKED device has a fragmentation layer enabling large packets to
 *  be fragmented and reassembled.  It is otherwise transparent to the
 *  user, and packets that are small enough to be sent without fragmentation
 *  are sent as single packets.
 */

/* Node ID and interface ID types */
typedef uint32_t node_id_t;
typedef uint32_t if_id_t;

/* RF broadcast address */
#define RF_BROADCAST 0xffffffff
#define INVALID_NID  0

/* RF Link Layer type field values */
#define RF_HB_TYPE       1
#define RF_STREAM_TYPE   2
#define RF_CLUSTER_TYPE  6


/* RF link layer packet format */
struct rf_pkt {
  if_id_t src;                  // source interface address 
  if_id_t dst;                  // destination interface address
  struct timeval rcv_time;    
  uint8_t type;                 // link layer packet type
  uint8_t reserved;             // pad byte
  uint8_t crc[2];               // link layer CRC
  uint8_t data[0];
};


/*
 *  Packet device API
 *
 *  The packet devices (RAW and COOKED variants) support multiple concurrent
 *  clients, queueing, and demultiplexing/filtering by type field.
 *
 *  Data transfer is sent by simple reads and writes to the device; one write
 *  per packet, and one read per packet.  The size of the next packet in the
 *  queue can be determined before the read occurs.  Packets that fail to match
 *  the type filter to not appear in the queue.
 *
 *  If a client sets loopback mode, all packets that are sent by any client will 
 *  also be looped to that client.  Messages sent to your own address will be
 *  looped back to all clients.
 *
 *  Filtering can be set up to filter for up to 128 packet types.  The calls
 *  rf_add_filter_type and rf_clr_filter_type can be used to add and remove
 *  filtering for specific types.  If a filter is installed for type X, Y, and Z,
 *  only packets matching those types will be received.  If no filters are
 *  installed, all traffic is received.  (Note: there is a race condition after
 *  opening the radio device and before installing a filter during which other
 *  traffic may be queued.  Thus it is wise to be tolerant of other type packets,
 *  while using filtering to reduce overhead)
 *
 *  All packets sent and received are preceded by a header (struct rf_pkt).
 *
 *  When sending a packet, you need only fill the dst and type fields.  
 *
 *  When receiving a packet, all fields are valid.  rcv_time is a timestamp
 *  generated in the kernel, and thus is relatively accurate. 
 *
 *  A convenient way to declare and send packets is the following:
 *
 *  struct {
 *    struct rf_pkt hdr;
 *    struct my_data_fields data;
 *  } packet = {
 *    hdr: {
 *      dst: send_to_some_addr,
 *      type: MY_PACKET_TYPE
 *    },
 *    data: {
 *      my_field: my_initializers
 *    }
 *  };
 * 
 *  int status = write(fd, *packet, sizeof(packet));
 *
 *  A convenient way to parse data out of a packet you have received is to 
 *  cast the "data" field of the struct rf_pkt to whatever type you are 
 *  expecting to find.  The data field is a 32-bit aligned pointer target.
 *
 *  e.g.  
 *    struct rf_pkt *incoming;
 *    int my_value = ((struct my_data_fields *)(incoming->data))->my_field;
 */

/* reads size of next packet */
int rf_get_front_size(int fd, int *len);

/* configures client filtering */
int rf_add_filter_type(int fd, int type);
int rf_clr_filter_type(int fd, int type);
int rf_clr_filter(int fd);
int rf_set_filter(int fd, rf_filter_t *filter);
int rf_get_filter(int fd, rf_filter_t *filter);

/* configures loopback mode */
int rf_set_loop_mode(int fd, int loop);
int rf_get_loop_mode(int fd, int *loop);

/* configures queue lengths */
int rf_set_incoming_qlen(int fd, int len);
int rf_get_incoming_qlen(int fd, int *len);
int rf_set_outgoing_qlen(int fd, int len);
int rf_get_outgoing_qlen(int fd, int *len);


/*
 *  RF configuation and status structures
 *
 *  The STATUS device of an RF interface returns a structure conforming
 *  to the specification below.
 */

/*
 *  generic status fields (for all radio interfaces) 
 */

typedef struct rf_stat {
  char type[20];
  char platform[20];
  if_id_t addr;
  if_id_t hb_addr;
  uint16_t power;
  uint16_t mtu;

  int RSSI;

  int framing_errors;
  int command_failures;
  int drop_crc;
  int drop_qlen;

  int bytes_tx;
  int packets_tx;

  int bytes_rx;
  int packets_rx;

} rf_stat_t;

/*
 *  status fields and values specific to the WINS rf modem
 */

#define RFMODEM_TYPE_STR     "RFModem"

#define RFMODEM_SLEEP_CAP      1
#define RFMODEM_SYNC_CAP       2
#define RFMODEM_STATUS_VALID   4
#define RFMODEM_BASE_MODE      8
#define RFMODEM_SLEEP_MODE    16
#define RFMODEM_FAILED        32

typedef struct rfmodem_stat {
  rf_stat_t s;

  uint8_t network;
  uint8_t arq;
  uint16_t mode;

  uint16_t hop_duration;
  uint16_t base_slot;

  if_id_t base_if_id;

  uint8_t point_to_point_mode;
  uint8_t max_remotes;
  uint16_t reserved;
  
  int drop_mtu;
  int drop_addr;
  int write_failures;  
} rfmodem_stat_t;


/*
 *  Status-related API calls
 *
 *  rf_get_status(dev_index) gets the current status for the specified interface
 *
 *  rf_read_status(fd) reads the current status from an open RAW or COOKED device
 *  rf_get_if_id(fd, *id) gets the interface ID of an open RAW or COOKED device
 *  rf_get_mtu(fd, *mtu) gets the current MTU of an open RAW or COOKED device
 *  rf_get_type(fd) returns a string describing an open RAW or COOKED device
 *
 *  rf_arq(dev_index) returns the number of retries in ARQ more, or 0 is ARQ is disabled
 *  rf_is_base(dev_index) returns 1 if the radio is a base, 0 if not, -1 if failed
 *
 *  rf_get_if_id_by_index(dev_index, *id) gets the interface ID of the specidied interface
 *  rf_get_node_id(*id) gets the node ID of this node
 */

rfmodem_stat_t * rf_get_status(int dev_index);

rfmodem_stat_t * rf_read_status(int fd);
int rf_get_if_id(int fd, if_id_t *id);
int rf_get_mtu(int fd, uint16_t *mtu);
char *rf_get_type(int fd);

int rf_arq(int dev_index);
int rf_is_base(int dev_index);

int rf_get_if_id_by_index(int devindex, if_id_t *id);
int rf_get_node_id(node_id_t *id);


/*
 *  rf_waitfor()
 *
 *  This call waits for the radio device to be ready for use.  This
 *  can be used to avoid problems during startup if your application
 *  starts running before the radio drivers have initialized.
 */

int rf_waitfor(int index);


/*
 *  Configuring RF interfaces
 *
 *  RF interfaces are configured by sending a command string to the COMMAND device.
 *  The commands accepted by that device are available by cat'ing the device (or 
 *  from documentation).  
 * 
 *  rf_printf_command(dev_index, fmt, ...) takes printf-style arguments and 
 *      issues a command to the specified rf interface.  
 *
 *  Some common examples:
 *
 *    To set the network number on radio 0:  rf_printf_command(0, "network=45");
 *    To set radio 1 to base:                rf_printf_command(1, "base");
 *    To set radio 0 to remote:              rf_printf_command(0, "remote");
 *    To sleep radio 0:                      rf_printf_command(0, "sleep");
 *
 *  rf_set_base(dev_index, base_mode) is a convenience function to set the
 *    radio to be base or remote depending on the base_mode parameter
 */

int rf_printf_command(int dev_index, const char *fmt, ...);
int rf_set_base(int dev_index, int base_mode);


/*
 *  Determining the base's address and Sending to the base
 *
 *  A common operation using clustered radios is sending to the base
 *
 *  rf_get_base_if_id() determines the interface address of the base
 *
 *  rf_send_to_base() sends the specified packet to the base.  If you
 *    are the base the packet will not be sent over the air, but will be
 *    looped back to all clients.  
 *
 *  Both of these functions take a rfmodem_stat_t **.  If a valid pointer 
 *  to a status struct is supplied, and that status structure contains
 *  a nonzero value for base_if_id, it is assumed to be the correct and is
 *  used.  Otherwise, the current status will be retrieved to determine the
 *  base address, and will be returned to the caller in the status pointer.
 */

int rf_get_base_if_id(int fd, if_id_t *id, rfmodem_stat_t **status);
int rf_send_to_base(int fd, struct rf_pkt *packet, size_t data_len, rfmodem_stat_t **status);


/*
 *  Neighbor List Interface
 *
 *  heartd's current neighbor list can be retrieved through an
 *  interface called "neighbors" (e.g. /dev/rf1/neighbors), with one
 *  neighbor interface per rf interface.
 * 
 *  The neighbors device will become selectable whenever there is a change, 
 *  AND every 10 seconds in order to heal broken lists (e.g to encourage a
 *  soft state approach INSIDE a system in addition to on the wire,
 *  which is where soft state is normally used)
 *
 *  Doing a read() will return a human-readable neighbor list for
 *  debugging purposes.
 *
 *  The hb_get_neighbor_list() function returns a binary form of the
 *  neighbor list data.  The last record is followed by a zeroed record;
 *  thus it is correct to loop over the data until a zeroed interface ID
 *  is encountered.
 */

typedef enum {
  UNDEFINED=0,			/* unknown neighbor state */
  SELF,				/* heartd has an entry for yourself */
  DEAD,				/* neighbor we once heard from, now dead */
  HALF_OPEN,			/* we've heard from them; don't know
                                   if they've heard from us yet */
  ACTIVE			/* full active, open, alive... */
} heart_state_t;


struct heartd_neighbor {
  if_id_t if_id;		/* interface address (>= 1 per node) */
  node_id_t node_id;		/* node address */
  uint32_t services;	        /* list of services ready on that node */
  time_t last_heard;		/* time of the most recent heartbeat */
  heart_state_t state;		/* what state this neighbor is in */
  uint8_t flags;		/* heartd flags set by the neighbor */
  uint8_t RSSI;			/* RSSI reported by the remote */
  uint8_t num_neighbors;	/* number of neighbors this neighbor has */
  uint8_t reserved;		/* pad */
};


/* 
 *  Clears the current neighbor list.  This is useful when you change networks
 *  or change from base to remote
 */

int hb_clear_neighbors(int dev_index);

/* 
 *  Gets the current neighbor list for specified device
 */

struct heartd_neighbor *hb_get_neighbors(int dev_index, int *count);
struct heartd_neighbor *hb_read_neighbors(int fd, int *count);

/* 
 *  used to map from radio interface ID to node ID and vice versa
 */

int hb_map_if_to_node(struct heartd_neighbor *n, if_id_t id, node_id_t *nid);
int hb_map_node_id_to_if_id(struct heartd_neighbor *n, node_id_t id, if_id_t *ifid);

/*
 *  helper function for pruning neighborlists.
 *  reallocates and returns a new list, with all entries removed for which
 *  the state field is zero.
 */

struct heartd_neighbor *hb_realloc_pruned(struct heartd_neighbor *n, size_t *returned_count);


/* Allow linkage to C or C++ */
__END_DECLS

#include <rf_util.h>

#endif