LEFT | RIGHT |
(no file at all) | |
| 1 /* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */ |
| 2 /* |
| 3 * Copyright (c) 2010 Network Security Lab, University of Washington, Seattle. |
| 4 * |
| 5 * This program is free software; you can redistribute it and/or modify |
| 6 * it under the terms of the GNU General Public License version 2 as |
| 7 * published by the Free Software Foundation; |
| 8 * |
| 9 * This program is distributed in the hope that it will be useful, |
| 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 12 * GNU General Public License for more details. |
| 13 * |
| 14 * You should have received a copy of the GNU General Public License |
| 15 * along with this program; if not, write to the Free Software |
| 16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| 17 * |
| 18 * Authors: Sidharth Nabar <snabar@uw.edu>, He Wu <mdzz@u.washington.edu> |
| 19 */ |
| 20 |
| 21 #ifndef WIRELESS_MODULE_UTILITY_H |
| 22 #define WIRELESS_MODULE_UTILITY_H |
| 23 |
| 24 #include "ns3/callback.h" |
| 25 #include "ns3/event-id.h" |
| 26 #include "ns3/packet.h" |
| 27 #include "ns3/object.h" |
| 28 #include "ns3/traced-callback.h" |
| 29 #include "ns3/nstime.h" |
| 30 #include "ns3/ptr.h" |
| 31 #include "ns3/random-variable.h" |
| 32 #include "ns3/traced-value.h" |
| 33 #include "ns3/node.h" |
| 34 |
| 35 namespace ns3 { |
| 36 |
| 37 /** |
| 38 * \brief Utilities module for wireless nodes. |
| 39 * |
| 40 * This class implements a utility modules which will provide basic PHY layer |
| 41 * functionalities and information to intelligence layer classes (jammer and/or |
| 42 * jamming mitigation). Currently this class is tailored to work with the wifi |
| 43 * protocol. |
| 44 */ |
| 45 class WirelessModuleUtility : public Object |
| 46 { |
| 47 public: |
| 48 /** |
| 49 * Structure to keep the basic information about the underlying PHY layer. |
| 50 * Only include parameters that are not protocol-specific. |
| 51 */ |
| 52 typedef struct PhyLayerInfo |
| 53 { |
| 54 double minTxPowerW; // minimum TX power for PHY layer in Watts |
| 55 double maxTxPowerW; // minimum TX power for PHY layer in Watts |
| 56 double TxGainDb; // Tx gain, in dB |
| 57 double RxGainDb; // Rx gain, in dB |
| 58 uint32_t phyRate; // PHY rate in bits per second |
| 59 uint16_t numOfChannels; // number of channels |
| 60 uint16_t currentChannel; // current channel number |
| 61 Time channelSwitchDelay; // channel switch delay |
| 62 } PhyLayerInfo; |
| 63 |
| 64 |
| 65 /** |
| 66 * Different modes for PHY layer send callback. |
| 67 */ |
| 68 enum PacketSendMode |
| 69 { |
| 70 SEND_AS_JAMMER = 0, |
| 71 SEND_AS_HONEST, |
| 72 SEND_AS_OTHERS |
| 73 }; |
| 74 |
| 75 /** |
| 76 * Callback type for RSS calculation in PHY. |
| 77 */ |
| 78 typedef Callback<double> UtilityRssCallback; |
| 79 |
| 80 /** |
| 81 * Callback type for sending packet in PHY. |
| 82 */ |
| 83 typedef Callback<void, Ptr<Packet>, double&, int> UtilitySendPacketCallback; |
| 84 |
| 85 /** |
| 86 * Callback for channel switch in PHY. |
| 87 */ |
| 88 typedef Callback<void, uint16_t> UtilityChannelSwitchCallback; |
| 89 |
| 90 /** |
| 91 * Callback for start/end of TX. |
| 92 */ |
| 93 typedef Callback<void, Ptr<Packet>, double> UtilityTxCallback; |
| 94 |
| 95 /** |
| 96 * Callback for handling start/end of RX. |
| 97 */ |
| 98 typedef Callback<bool, Ptr<Packet>, double> UtilityRxCallback; |
| 99 |
| 100 public: |
| 101 static TypeId GetTypeId (void); |
| 102 WirelessModuleUtility (); |
| 103 virtual ~WirelessModuleUtility (); |
| 104 |
| 105 // setters and getters for attributes |
| 106 void SetThroughputUpdateInterval (Time updateInterval); |
| 107 Time GetThroughputUpdateInterval (void) const; |
| 108 void SetPdrWindowSize (uint32_t pdrWindowSize); |
| 109 uint32_t GetPdrWindowSize (void) const; |
| 110 void SetRssUpdateInterval (Time updateInterval); |
| 111 Time GetRssUpdateInterval (void) const; |
| 112 |
| 113 // access functions to member variables |
| 114 void SetRssMeasurementCallback (UtilityRssCallback RssCallback); |
| 115 void SetInclusionList (std::vector<std::string> list); |
| 116 void SetExclusionList (std::vector<std::string> list); |
| 117 void SetSendPacketCallback (UtilitySendPacketCallback sendPacketCallback); |
| 118 void SetChannelSwitchCallback (UtilityChannelSwitchCallback channelSwitchCallb
ack); |
| 119 void SetStartTxCallback (UtilityTxCallback startTxCallback); |
| 120 void SetEndTxCallback (UtilityTxCallback endTxCallback); |
| 121 void SetStartRxCallback (UtilityRxCallback startRxCallback); |
| 122 void SetEndRxCallback (UtilityRxCallback endRxCallback); |
| 123 void SetPhyLayerInfo (PhyLayerInfo info); |
| 124 PhyLayerInfo GetPhyLayerInfo (void) const; |
| 125 ·· |
| 126 /** |
| 127 * \brief Handle a start of packet reception event. |
| 128 * |
| 129 * \param packet Pointer to the packet to be received. |
| 130 * \param startRss RSS at the start of the packet. |
| 131 * \returns True if the incoming packet is to be received. False if the packet |
| 132 * is to be dropped. |
| 133 * |
| 134 * Implementation of this function is based on YansWifiPhy class, it may not |
| 135 * be directly applicable to other wireless protocols. For reactive jammers, |
| 136 * it stops receiving the rest of the packet as soon as the preambles are |
| 137 * received. This function invokes the StartRxHandler callback in reactive |
| 138 * jammer to stop receiving current packet and start sending jamming signals. |
| 139 */ |
| 140 bool StartRxHandler (Ptr<Packet> packet, double startRss); |
| 141 · |
| 142 /** |
| 143 * \brief Handle an end of packet reception notification. |
| 144 * |
| 145 * \param packet Pointer to packet that has been received. |
| 146 * \param averageRss Average RSS over the reception of the packet. |
| 147 * \param isSuccessfullyReceived True if packets was received successfully. |
| 148 * |
| 149 * This function forwards the received packet to appropriate callbacks. It |
| 150 * is called inside by PHY layer driver at EndRx. |
| 151 */ |
| 152 void EndRxHandler (Ptr<Packet> packet, double averageRss, |
| 153 const bool isSuccessfullyReceived); |
| 154 ········································ |
| 155 /** |
| 156 * \brief Handle the start of packet TX event. |
| 157 * |
| 158 * \param packet Pointer to the packet that is being sent. |
| 159 * \param txPower TX power used for the transmission of the packet. |
| 160 * |
| 161 * This function is called by PHY layer driver at the beginning of TX, used |
| 162 * for throughput recording. |
| 163 */ |
| 164 void StartTxHandler (Ptr<const Packet> packet, double txPower); |
| 165 · |
| 166 /** |
| 167 * \brief Handle the end of packet TX event. |
| 168 * |
| 169 * \param packet Pointer to the packet that is being sent. |
| 170 * \param txPower TX power used for the transmission of the packet. |
| 171 * |
| 172 * This function invokes appropriate callbacks for the end of TX. Mainly used |
| 173 * by jammers for scheduling jamming events. |
| 174 */ |
| 175 void EndTxHandler (Ptr<const Packet> packet, double txPower); |
| 176 |
| 177 /** |
| 178 * \returns Total bytes received. |
| 179 */ |
| 180 uint64_t GetTotalBytesRx (void) const; |
| 181 |
| 182 /** |
| 183 * \returns Total bytes sent. |
| 184 */ |
| 185 uint64_t GetTotalBytesTx (void) const; |
| 186 |
| 187 /** |
| 188 * \returns Rx throughput. |
| 189 */ |
| 190 double GetRxThroughput (void) const; |
| 191 |
| 192 /** |
| 193 * \returns Tx throughput. |
| 194 */ |
| 195 double GetTxThroughput (void) const; |
| 196 |
| 197 /** |
| 198 * \returns Current PDR. |
| 199 */ |
| 200 double GetPdr (void) const; |
| 201 |
| 202 /** |
| 203 * \returns Current node RSS. |
| 204 */ |
| 205 double GetRss (void) const; |
| 206 |
| 207 /** |
| 208 * \brief Used by jammers to send out a jamming signal of a given power level |
| 209 * and duration. |
| 210 * |
| 211 * \param power double indicating the power of the jamming signal to be sent |
| 212 * \param duration Duration of the jamming burst |
| 213 * \returns TX power (in Watts) the signal is actually sent with. |
| 214 * |
| 215 * This function sends jamming signal of specific power via the PHY layer. If |
| 216 * the sending power is not supported by the PHY layer. The signal power will |
| 217 * be scaled to the nearest supported value. |
| 218 */ |
| 219 double SendJammingSignal (double power, Time duration); |
| 220 |
| 221 /** |
| 222 * \brief This function switches the PHY channel number. |
| 223 * |
| 224 * \param channelNumber Desired channel number to switch to. |
| 225 */ |
| 226 void SwitchChannel (uint16_t channelNumber); |
| 227 |
| 228 /** |
| 229 * \brief Sends jamming mitigation message (packet) at specified power. |
| 230 * |
| 231 * \param packet Mitigation message (packet) to be sent. |
| 232 * \param power Power (in Watts) to send the packet. |
| 233 * \returns Actual power the packet is set with. |
| 234 * |
| 235 * Similar to SendJammingSignal, this function will scale the signal power if |
| 236 * it is not supported by underlying PHY layer. |
| 237 */ |
| 238 double SendMitigationMessage (Ptr<Packet> packet, double power); |
| 239 |
| 240 private: |
| 241 void DoStart (void); |
| 242 void DoDispose (void); |
| 243 |
| 244 /** |
| 245 * \brief "Packet Monitor" that analyzes and records incoming packets. |
| 246 * |
| 247 * \param packet The incoming packet. |
| 248 * \param isSuccessfullyReceived True if packet was received successfully. |
| 249 * |
| 250 * This function is called by the EndRxHandler. It analyzes incoming packets |
| 251 * to extract and record packet type, length, etc. Filtering to analyze only |
| 252 * packets with certain headers and/or trailers can be done by specifying the |
| 253 * header/trailer inclusion and exclusion list. |
| 254 */ |
| 255 void AnalyzeAndRecordIncomingPacket (const Ptr<Packet> packet, |
| 256 bool isSuccessfullyReceived); |
| 257 /** |
| 258 * \brief "Packet Monitor" that analyzes and records outgoing packets. |
| 259 * |
| 260 * This function can be called by StartTxHandler. See |
| 261 * AnalyzeAndRecordIncomingPacket(). |
| 262 */ |
| 263 void AnalyzeAndRecordOutgoingPacket (Ptr<const Packet> packet); |
| 264 |
| 265 /** |
| 266 * This function updates RX/TX throughput. |
| 267 */ |
| 268 void UpdateThroughput (void); |
| 269 |
| 270 /** |
| 271 * \param packet Target packet. |
| 272 * \param headerName Name of header to search for |
| 273 * \returns Size of the header, 0 if header not found |
| 274 * |
| 275 * This function searches the incoming packet for desired header/trailer. |
| 276 * Modified from "void Packet::Print (std::ostream &os) const". |
| 277 */ |
| 278 uint32_t FindHeader (Ptr<const Packet> packet, std::string headerName) const; |
| 279 |
| 280 /** |
| 281 * \brief Checks if headers/trailers in the inclusion list is in the given |
| 282 * packet. |
| 283 * \param packet Packet to check |
| 284 * \returns True if headers/trailers in the inclusion list are found in the |
| 285 * packet. |
| 286 * |
| 287 * This function checks if headers/trailers in the inclusion list are present |
| 288 * in the given packet. Used in UpdateThroughput function to exclude certain |
| 289 * types of packets. Note that if the inclusion list is empty (means we are |
| 290 * accepting packets with any header/trailer), this function returns true. |
| 291 */ |
| 292 bool FindHeaderInInclusionList (Ptr<const Packet> packet); |
| 293 |
| 294 /** |
| 295 * \see FindHeaderInInclusionList (); |
| 296 */ |
| 297 bool FindHeaderInExclusionList (Ptr<const Packet> packet); |
| 298 |
| 299 /** |
| 300 * \param isPacketValid True if packet is successfully received. |
| 301 * |
| 302 * This function updates PDR. |
| 303 */ |
| 304 void UpdatePdr (const bool isPacketValid); |
| 305 |
| 306 /** |
| 307 * \param newPacketStatus True if packet is successfully received. |
| 308 * |
| 309 * This function inserts the packet status into the packet status list. |
| 310 */ |
| 311 void InsertIntoPdrArray (bool newPacketStatus); |
| 312 |
| 313 /** |
| 314 * This function updates current RSS reading. Initially scheduled at |
| 315 * StartRxHandler (). |
| 316 */ |
| 317 void UpdateRss (void); |
| 318 |
| 319 /** |
| 320 * \brief Convert dBm to Watts. |
| 321 * |
| 322 * \param dBm Original value. |
| 323 * \returns Converted value. |
| 324 */ |
| 325 double DbmToW (double dBm) const; |
| 326 |
| 327 /** |
| 328 * \brief Convert Watts to dBm. |
| 329 * |
| 330 * \param w Original value. |
| 331 * \returns Converted value. |
| 332 */ |
| 333 double WToDbm (double w) const; |
| 334 |
| 335 private: |
| 336 PhyLayerInfo m_phyLayerInfo; |
| 337 ·· |
| 338 // throughput recording |
| 339 TracedValue<uint64_t> m_totalBytesRx; // variable keeping track of total byte
s received |
| 340 TracedValue<uint64_t> m_totalBytesTx; // variable keeping track of total byte
s sent |
| 341 uint64_t m_previousTotalBytesRx; |
| 342 uint64_t m_previousTotalBytesTx; |
| 343 TracedValue<double> m_throughputRx; // RX throughput = derivative of total byt
es RX |
| 344 TracedValue<double> m_throughputTx; // TX throughput = derivative of total byt
es TX |
| 345 Time m_throughputUpdateInterval; // throughput update interval |
| 346 EventId m_throughputUpdateEvent; // event ID for throughput update event |
| 347 std::vector<std::string> m_headerInclusionList; // header/trailer inclusion li
st |
| 348 std::vector<std::string> m_headerExclusionList; // header/trailer exclusion li
st |
| 349 |
| 350 // PDR recording |
| 351 TracedValue<double> m_Pdr; // variable keeping track of PDR |
| 352 uint32_t m_pdrWindowSize; // PDR recording window size |
| 353 uint32_t m_numOfPktsRecvd; // total # of packets received |
| 354 uint32_t m_pdrArrayCurIndex; // current index of PDR array |
| 355 std::vector<bool> m_pktStatusRecord; // List of validity of last N packets |
| 356 |
| 357 // RSS recording |
| 358 TracedValue<double> m_nodeRssW; // current RSS reading at node, in watts, -1
indicates error |
| 359 Time m_rssUpdateInterval; // RSS update interval |
| 360 EventId m_updateRssEvent; // event ID for RSS update event |
| 361 TracedValue<double> m_avgPktRssW; // average packet RSS for previously receive
d packet |
| 362 |
| 363 /** |
| 364 * Callback for measure current RSS (in watts). Done by PHY layer driver. |
| 365 * Returns -1 if no valid RSS calculation is available yet. |
| 366 * |
| 367 * The PHY layer driver for wifi is required to keep a copy of the latest |
| 368 * WifiMode it's currently operating on, for the interference helper to |
| 369 * calculate RSS. Implementation of callbacks is specific to the PHY layer |
| 370 * protocol. However the callback's format is generic and applicable for |
| 371 * different wireless protocols (PHY classes). |
| 372 */ |
| 373 UtilityRssCallback m_rssMeasurementCallback; |
| 374 /** |
| 375 * Callback for sending a packet out through the PHY layer.· |
| 376 *· |
| 377 * Implementation of callbacks is specific to the PHY layer protocol. However |
| 378 * the callback's format is generic and applicable for different wireless |
| 379 * protocols (PHY classes). |
| 380 */ |
| 381 UtilitySendPacketCallback m_sendPacketCallback; |
| 382 /** |
| 383 * Callback for switching channels in PHY. |
| 384 * |
| 385 * Implementation of callbacks is specific to the PHY. However the callback's |
| 386 * format is generic and applicable for different wireless protocols (PHY |
| 387 * classes). Note that this callback should not be set if channel switch is |
| 388 * not supported by the PHY. |
| 389 */ |
| 390 UtilityChannelSwitchCallback m_channelSwitchCallback; |
| 391 /** |
| 392 * Callback to handle start of TX, not used for now. |
| 393 */ |
| 394 UtilityTxCallback m_startTxCallback; |
| 395 /** |
| 396 * Callback to handle end of TX, used by jamming mitigation. |
| 397 */ |
| 398 UtilityTxCallback m_endTxCallback; |
| 399 /** |
| 400 * Callback to handle start of RX, used by jammers. |
| 401 */ |
| 402 UtilityRxCallback m_startRxCallback; |
| 403 /** |
| 404 * Callback for packet handler in jammer or jamming mitigation. |
| 405 */ |
| 406 UtilityRxCallback m_endRxCallback; |
| 407 |
| 408 }; |
| 409 |
| 410 } // namespace ns3 |
| 411 |
| 412 #endif /* WIRELESS_MODULE_UTILITY_H */ |
LEFT | RIGHT |