PageRenderTime 53ms CodeModel.GetById 28ms RepoModel.GetById 0ms app.codeStats 0ms

/src/network/utils/error-model.h

https://bitbucket.org/cttc-lena/ns-3-lena-dev
C Header | 464 lines | 104 code | 46 blank | 314 comment | 0 complexity | a73c90bf660db081c9e69dea2c7d68ae MD5 | raw file
Possible License(s): GPL-2.0
  1. /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
  2. /*
  3. * Copyright (c) 2007 University of Washington
  4. * Copyright (c) 2013 ResiliNets, ITTC, University of Kansas
  5. *
  6. * This program is free software; you can redistribute it and/or modify
  7. * it under the terms of the GNU General Public License version 2 as
  8. * published by the Free Software Foundation;
  9. *
  10. * This program is distributed in the hope that it will be useful,
  11. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13. * GNU General Public License for more details.
  14. *
  15. * You should have received a copy of the GNU General Public License
  16. * along with this program; if not, write to the Free Software
  17. * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  18. *
  19. *
  20. * This file incorporates work covered by the following copyright and
  21. * permission notice:
  22. *
  23. * Copyright (c) 1997 Regents of the University of California.
  24. * All rights reserved.
  25. *
  26. * Redistribution and use in source and binary forms, with or without
  27. * modification, are permitted provided that the following conditions
  28. * are met:
  29. * 1. Redistributions of source code must retain the above copyright
  30. * notice, this list of conditions and the following disclaimer.
  31. * 2. Redistributions in binary form must reproduce the above copyright
  32. * notice, this list of conditions and the following disclaimer in the
  33. * documentation and/or other materials provided with the distribution.
  34. * 3. Neither the name of the University nor of the Laboratory may be used
  35. * to endorse or promote products derived from this software without
  36. * specific prior written permission.
  37. *
  38. * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  39. * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40. * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  41. * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  42. * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  43. * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  44. * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  45. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  46. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  47. * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  48. * SUCH DAMAGE.
  49. *
  50. * Contributed by the Daedalus Research Group, UC Berkeley
  51. * (http://daedalus.cs.berkeley.edu)
  52. *
  53. * This code has been ported from ns-2 (queue/errmodel.{cc,h}
  54. */
  55. /* BurstErrorModel additions
  56. *
  57. * Author: Truc Anh N. Nguyen <annguyen@ittc.ku.edu>
  58. * ResiliNets Research Group http://wiki.ittc.ku.edu/resilinets
  59. * James P.G. Sterbenz <jpgs@ittc.ku.edu>, director
  60. */
  61. #ifndef ERROR_MODEL_H
  62. #define ERROR_MODEL_H
  63. #include <list>
  64. #include "ns3/object.h"
  65. #include "ns3/random-variable-stream.h"
  66. namespace ns3 {
  67. class Packet;
  68. /**
  69. * \ingroup network
  70. * \defgroup errormodel Error Model
  71. */
  72. /**
  73. * \ingroup errormodel
  74. * \brief General error model that can be used to corrupt packets
  75. *
  76. * This object is used to flag packets as being lost/errored or not.
  77. * It is part of the Object framework and can be aggregated to
  78. * other ns3 objects and handled by the Ptr class.
  79. *
  80. * The main method is IsCorrupt(Ptr<Packet> p) which returns true if
  81. * the packet is to be corrupted according to the underlying model.
  82. * Depending on the error model, the packet itself may have its packet
  83. * data buffer errored or not, or side information may be returned to
  84. * the client in the form of a packet tag. (Note: No such error models
  85. * that actually error the bits in a packet presently exist).
  86. * The object can have state (resettable by Reset()).
  87. * The object can also be enabled and disabled via two public member functions.
  88. *
  89. * Typical code (simplified) to use an ErrorModel may look something like
  90. * this:
  91. * \code
  92. * Ptr<ErrorModel> rem = CreateObject<RateErrorModel> ();
  93. * Ptr<UniformRandomVariable> uv = CreateObject<UniformRandomVariable> ();
  94. * rem->SetRandomVariable (uv);
  95. * rem->SetRate (0.001);
  96. * ...
  97. * Ptr<Packet> p;
  98. * if (rem->IsCorrupt (p))
  99. * {
  100. * dropTrace(p);
  101. * } else {
  102. * Forward (p);
  103. * }
  104. * \endcode
  105. *
  106. * Four practical error models, a RateErrorModel, a BurstErrorModel,
  107. * a ListErrorModel, and a ReceiveListErrorModel, are currently implemented.
  108. */
  109. class ErrorModel : public Object
  110. {
  111. public:
  112. /**
  113. * \brief Get the type ID.
  114. * \return the object TypeId
  115. */
  116. static TypeId GetTypeId (void);
  117. ErrorModel ();
  118. virtual ~ErrorModel ();
  119. /**
  120. * Note: Depending on the error model, this function may or may not
  121. * alter the contents of the packet upon returning true.
  122. *
  123. * \returns true if the Packet is to be considered as errored/corrupted
  124. * \param pkt Packet to apply error model to
  125. */
  126. bool IsCorrupt (Ptr<Packet> pkt);
  127. /**
  128. * Reset any state associated with the error model
  129. */
  130. void Reset (void);
  131. /**
  132. * Enable the error model
  133. */
  134. void Enable (void);
  135. /**
  136. * Disable the error model
  137. */
  138. void Disable (void);
  139. /**
  140. * \return true if error model is enabled; false otherwise
  141. */
  142. bool IsEnabled (void) const;
  143. private:
  144. /**
  145. * Corrupt a packet according to the specified model.
  146. * \param p the packet to corrupt
  147. * \returns true if the packet is corrupted
  148. */
  149. virtual bool DoCorrupt (Ptr<Packet> p) = 0;
  150. /**
  151. * Re-initialize any state
  152. */
  153. virtual void DoReset (void) = 0;
  154. bool m_enable; //!< True if the error model is enabled
  155. };
  156. /**
  157. * \brief Determine which packets are errored corresponding to an underlying
  158. * distribution, rate, and unit.
  159. *
  160. * This object is used to flag packets as being lost/errored or not.
  161. * The two parameters that govern the behavior are the rate (or
  162. * equivalently, the mean duration/spacing between errors), and the
  163. * unit (which may be per-bit, per-byte, and per-packet).
  164. * Users can optionally provide a RandomVariableStream object; the default
  165. * is to use a Uniform(0,1) distribution.
  166. * Reset() on this model will do nothing
  167. *
  168. * IsCorrupt() will not modify the packet data buffer
  169. */
  170. class RateErrorModel : public ErrorModel
  171. {
  172. public:
  173. /**
  174. * \brief Get the type ID.
  175. * \return the object TypeId
  176. */
  177. static TypeId GetTypeId (void);
  178. RateErrorModel ();
  179. virtual ~RateErrorModel ();
  180. /**
  181. * Error unit. The error model can be packet, Byte or bit based.
  182. */
  183. enum ErrorUnit
  184. {
  185. ERROR_UNIT_BIT,
  186. ERROR_UNIT_BYTE,
  187. ERROR_UNIT_PACKET
  188. };
  189. /**
  190. * \returns the ErrorUnit being used by the underlying model
  191. */
  192. RateErrorModel::ErrorUnit GetUnit (void) const;
  193. /**
  194. * \param error_unit the ErrorUnit to be used by the underlying model
  195. */
  196. void SetUnit (enum ErrorUnit error_unit);
  197. /**
  198. * \returns the error rate being applied by the model
  199. */
  200. double GetRate (void) const;
  201. /**
  202. * \param rate the error rate to be used by the model
  203. */
  204. void SetRate (double rate);
  205. /**
  206. * \param ranvar A random variable distribution to generate random variates
  207. */
  208. void SetRandomVariable (Ptr<RandomVariableStream>);
  209. /**
  210. * Assign a fixed random variable stream number to the random variables
  211. * used by this model. Return the number of streams (possibly zero) that
  212. * have been assigned.
  213. *
  214. * \param stream first stream index to use
  215. * \return the number of stream indices assigned by this model
  216. */
  217. int64_t AssignStreams (int64_t stream);
  218. private:
  219. virtual bool DoCorrupt (Ptr<Packet> p);
  220. /**
  221. * Corrupt a packet (packet unit).
  222. * \param p the packet to corrupt
  223. * \returns true if the packet is corrupted
  224. */
  225. virtual bool DoCorruptPkt (Ptr<Packet> p);
  226. /**
  227. * Corrupt a packet (Byte unit).
  228. * \param p the packet to corrupt
  229. * \returns true if the packet is corrupted
  230. */
  231. virtual bool DoCorruptByte (Ptr<Packet> p);
  232. /**
  233. * Corrupt a packet (bit unit).
  234. * \param p the packet to corrupt
  235. * \returns true if the packet is corrupted
  236. */
  237. virtual bool DoCorruptBit (Ptr<Packet> p);
  238. virtual void DoReset (void);
  239. enum ErrorUnit m_unit; //!< Error rate unit
  240. double m_rate; //!< Error rate
  241. Ptr<RandomVariableStream> m_ranvar; //!< rng stream
  242. };
  243. /**
  244. * \brief Determine which bursts of packets are errored corresponding to
  245. * an underlying distribution, burst rate, and burst size.
  246. *
  247. * This object is used to flag packets as being lost/errored or not.
  248. * The two parameters that govern the behavior are the burst rate (or
  249. * equivalently, the mean duration/spacing between between error events),
  250. * and the burst size (or equivalently, the number of packets being flagged
  251. * as errored at each error event).
  252. *
  253. * Users can optionally provide RandomVariableStream objects;
  254. * the default for the decision variable is to use a Uniform(0,1) distribution;
  255. * the default for the burst size (number of packets) is to use a
  256. * discrete Uniform[1,4] distribution.
  257. *
  258. * For every packet, the model generates a random number based on the
  259. * decision variable, and compares it with the burst error rate to
  260. * determine if a burst error event should occur.
  261. * If a new error event occurs, the model to will generate a new burst size
  262. * to determine how many packets should be dropped in this particular burst
  263. * error event in addition to the current packet.
  264. *
  265. * When a second packet arrives, the model again determines if a new error
  266. * event should occur based on a newly generated decision variable and
  267. * the burst error rate. If a new error event is determined to occur,
  268. * the model will restart with a new burst size. Otherwise, the model will
  269. * resume the last error event and drop the packet provided that the
  270. * total number of packets that has been dropped does not exceed the
  271. * burst size.
  272. *
  273. * IsCorrupt() will not modify the packet data buffer
  274. */
  275. class BurstErrorModel : public ErrorModel
  276. {
  277. public:
  278. /**
  279. * \brief Get the type ID.
  280. * \return the object TypeId
  281. */
  282. static TypeId GetTypeId (void);
  283. BurstErrorModel ();
  284. virtual ~BurstErrorModel ();
  285. /**
  286. * \returns the error rate being applied by the model
  287. */
  288. double GetBurstRate (void) const;
  289. /**
  290. * \param rate the error rate to be used by the model
  291. */
  292. void SetBurstRate (double rate);
  293. /**
  294. * \param ranVar A random variable distribution to generate random variates
  295. */
  296. void SetRandomVariable (Ptr<RandomVariableStream> ranVar);
  297. /**
  298. * \param burstSz A random variable distribution to generate random burst size
  299. */
  300. void SetRandomBurstSize (Ptr<RandomVariableStream> burstSz);
  301. /**
  302. * Assign a fixed random variable stream number to the random variables
  303. * used by this model. Return the number of streams (possibly zero) that
  304. * have been assigned.
  305. *
  306. * \param stream first stream index to use
  307. * \return the number of stream indices assigned by this model
  308. */
  309. int64_t AssignStreams (int64_t stream);
  310. private:
  311. virtual bool DoCorrupt (Ptr<Packet> p);
  312. virtual void DoReset (void);
  313. double m_burstRate; //!< the burst error event
  314. Ptr<RandomVariableStream> m_burstStart; //!< the error decision variable
  315. Ptr<RandomVariableStream> m_burstSize; //!< the number of packets being flagged as errored
  316. /**
  317. * keep track of the number of packets being errored
  318. * until it reaches m_burstSize
  319. */
  320. uint32_t m_counter;
  321. uint32_t m_currentBurstSz; //!< the current burst size
  322. };
  323. /**
  324. * \brief Provide a list of Packet uids to corrupt
  325. *
  326. * This object is used to flag packets as being lost/errored or not.
  327. * A note on performance: the list is assumed to be unordered, and
  328. * in general, Packet uids received may be unordered. Therefore,
  329. * each call to IsCorrupt() will result in a walk of the list with
  330. * the present underlying implementation.
  331. *
  332. * Note also that if one wants to target multiple packets from looking
  333. * at an (unerrored) trace file, the act of erroring a given packet may
  334. * cause subsequent packet uids to change. For instance, suppose one wants
  335. * to error packets 11 and 17 on a given device. It may be that erroring
  336. * packet 11 will cause the subsequent uid stream to change and 17 may no
  337. * longer correspond to the second packet that one wants to lose. Therefore,
  338. * be advised that it might take some trial and error to select the
  339. * right uids when multiple are provided.
  340. *
  341. * Reset() on this model will clear the list
  342. *
  343. * IsCorrupt() will not modify the packet data buffer
  344. */
  345. class ListErrorModel : public ErrorModel
  346. {
  347. public:
  348. /**
  349. * \brief Get the type ID.
  350. * \return the object TypeId
  351. */
  352. static TypeId GetTypeId (void);
  353. ListErrorModel ();
  354. virtual ~ListErrorModel ();
  355. /**
  356. * \return a copy of the underlying list
  357. */
  358. std::list<uint32_t> GetList (void) const;
  359. /**
  360. * \param packetlist The list of packet uids to error.
  361. *
  362. * This method overwrites any previously provided list.
  363. */
  364. void SetList (const std::list<uint32_t> &packetlist);
  365. private:
  366. virtual bool DoCorrupt (Ptr<Packet> p);
  367. virtual void DoReset (void);
  368. /// Typedef: packet Uid list
  369. typedef std::list<uint32_t> PacketList;
  370. /// Typedef: packet Uid list const iterator
  371. typedef std::list<uint32_t>::const_iterator PacketListCI;
  372. PacketList m_packetList; //!< container of Uid of packets to corrupt
  373. };
  374. /**
  375. * \brief Provide a list of Packets to corrupt
  376. *
  377. * This model also processes a user-generated list of packets to
  378. * corrupt, except that the list corresponds to the sequence of
  379. * received packets as observed by this error model, and not the
  380. * Packet UID.
  381. *
  382. * Reset() on this model will clear the list
  383. *
  384. * IsCorrupt() will not modify the packet data buffer
  385. */
  386. class ReceiveListErrorModel : public ErrorModel
  387. {
  388. public:
  389. /**
  390. * \brief Get the type ID.
  391. * \return the object TypeId
  392. */
  393. static TypeId GetTypeId (void);
  394. ReceiveListErrorModel ();
  395. virtual ~ReceiveListErrorModel ();
  396. /**
  397. * \return a copy of the underlying list
  398. */
  399. std::list<uint32_t> GetList (void) const;
  400. /**
  401. * \param packetlist The list of packets to error.
  402. *
  403. * This method overwrites any previously provided list.
  404. */
  405. void SetList (const std::list<uint32_t> &packetlist);
  406. private:
  407. virtual bool DoCorrupt (Ptr<Packet> p);
  408. virtual void DoReset (void);
  409. /// Typedef: packet sequence number list
  410. typedef std::list<uint32_t> PacketList;
  411. /// Typedef: packet sequence number list const iterator
  412. typedef std::list<uint32_t>::const_iterator PacketListCI;
  413. PacketList m_packetList; //!< container of sequence number of packets to corrupt
  414. uint32_t m_timesInvoked; //!< number of times the error model has been invoked
  415. };
  416. } // namespace ns3
  417. #endif