Contiki 2.6

collect-link-estimate.h

Go to the documentation of this file.
00001 /**
00002  * \addtogroup rime
00003  * @{
00004  */
00005 /**
00006  * \defgroup rimelinkestimate Link estimate management
00007  *
00008  * The link estimate module is used for computing estimations of link
00009  * quality. It computes a quality index for links, based on
00010  * information about how many times a packet has been transmitted, as
00011  * well as information about incoming packets. The link estimate
00012  * module exposes an interface that provides functions that are called
00013  * for incoming and outgoing packets.
00014  */
00015 /*
00016  * Copyright (c) 2010, Swedish Institute of Computer Science.
00017  * All rights reserved.
00018  *
00019  * Redistribution and use in source and binary forms, with or without
00020  * modification, are permitted provided that the following conditions
00021  * are met:
00022  * 1. Redistributions of source code must retain the above copyright
00023  *    notice, this list of conditions and the following disclaimer.
00024  * 2. Redistributions in binary form must reproduce the above copyright
00025  *    notice, this list of conditions and the following disclaimer in the
00026  *    documentation and/or other materials provided with the distribution.
00027  * 3. Neither the name of the Institute nor the names of its contributors
00028  *    may be used to endorse or promote products derived from this software
00029  *    without specific prior written permission.
00030  *
00031  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00032  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00033  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00034  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00035  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00036  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00037  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00038  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00039  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00040  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00041  * SUCH DAMAGE.
00042  *
00043  * This file is part of the Contiki operating system.
00044  *
00045  * $Id: collect-link-estimate.h,v 1.4 2011/01/09 21:14:22 adamdunkels Exp $
00046  */
00047 
00048 /**
00049  * \file
00050  *         Header file for the Collect link estimate
00051  * \author
00052  *         Adam Dunkels <adam@sics.se>
00053  */
00054 
00055 #ifndef COLLECT_LINK_ESTIMATE_H
00056 #define COLLECT_LINK_ESTIMATE_H
00057 
00058 #define COLLECT_LINK_ESTIMATE_UNIT           8
00059 
00060 
00061 
00062 struct collect_link_estimate {
00063   uint32_t etx_accumulator;
00064   uint8_t num_estimates;
00065 };
00066 
00067 /**
00068  * \brief      Initialize a new link estimate
00069  * \param le   A pointer to a link estimate structure
00070  *
00071  *             This function initializes a link estimate.
00072  */
00073 void collect_link_estimate_new(struct collect_link_estimate *le);
00074 
00075 /**
00076  * \brief      Update a link estimate when a packet has been sent.
00077  * \param le   A pointer to a link estimate structure
00078  * \param num_tx The number of times the packet was transmitted before it was ACKed
00079  *
00080  *             This function updates a link estimate. This function is
00081  *             called when a packet has been sent. The function may
00082  *             use information from the packet buffer and the packet
00083  *             buffer attributes when computing the link estimate.
00084  */
00085 void collect_link_estimate_update_tx(struct collect_link_estimate *le,
00086                                      uint8_t num_tx);
00087 
00088 /**
00089  * \brief      Update a link estimate when a packet has failed to be sent.
00090  * \param le   A pointer to a link estimate structure
00091  * \param num_tx The number of times the packet was transmitted before it was given up on.
00092  *
00093  *             This function updates a link estimate. This function is
00094  *             called when a packet has been sent. The function may
00095  *             use information from the packet buffer and the packet
00096  *             buffer attributes when computing the link estimate.
00097  */
00098 void collect_link_estimate_update_tx_fail(struct collect_link_estimate *le,
00099                                           uint8_t num_tx);
00100 
00101 /**
00102  * \brief      Update a link estimate when a packet has been received.
00103  * \param le   A pointer to a link estimate structure
00104  *
00105  *             This function updates a link estimate. This function is
00106  *             called when a packet has been received. The function
00107  *             uses information from the packet buffer and its
00108  *             attributes.
00109  */
00110 void collect_link_estimate_update_rx(struct collect_link_estimate *le);
00111 
00112 
00113 /**
00114  * \brief      Compute the link estimate metric for a link estimate
00115  * \param le   A pointer to a link estimate structure
00116  * \return     The current link estimate metric
00117  *
00118  */
00119 uint16_t collect_link_estimate(struct collect_link_estimate *le);
00120 
00121 int collect_link_estimate_num_estimates(struct collect_link_estimate *le);
00122 
00123 #endif /* COLLECT_LINK_ESTIMATE_H */
00124 
00125 /** @} */