src/ats/test_ats_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010-2015 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      Affero General Public License for more details.
  14 */
  15 /**
  16  * @file ats/test_ats_lib.h
  17  * @brief test ATS library with a generic interpreter for running ATS tests
  18  * @author Christian Grothoff
  19  */
  20 #ifndef TEST_ATS_LIB_H
  21 #define TEST_ATS_LIB_H
  22
  23 #include "gnunet_util_lib.h"
  24 #include "gnunet_ats_service.h"
  25 #include "gnunet_testing_lib.h"
  26
  27
  28 /**
  29  * Commands for the interpreter.
  30  */
  31 enum CommandCode
  32 {
  33   /**
  34    * End the test (passing).
  35    */
  36   CMD_END_PASS = 0,
  37
  38   /**
  39    * Call #GNUNET_ATS_address_add().
  40    */
  41   CMD_ADD_ADDRESS,
  42
  43   /**
  44    * Call #GNUNET_ATS_address_del().
  45    */
  46   CMD_DEL_ADDRESS,
  47
  48   /**
  49    * Wait for ATS to suggest address.
  50    */
  51   CMD_AWAIT_ADDRESS_SUGGESTION,
  52
  53   /**
  54    * Wait for ATS to suggest disconnect.
  55    */
  56   CMD_AWAIT_DISCONNECT_SUGGESTION,
  57
  58   /**
  59    * Ask ATS to connect to a peer, using
  60    * #GNUNET_ATS_connectivity_suggest().
  61    */
  62   CMD_REQUEST_CONNECTION_START,
  63
  64   /**
  65    * Tell ATS we no longer need a connection to a peer, using
  66    * #GNUNET_ATS_connectivity_suggest_cancel().
  67    */
  68   CMD_REQUEST_CONNECTION_STOP,
  69
  70   /**
  71    * Wait for certain address information to be provided.
  72    */
  73   CMD_AWAIT_ADDRESS_INFORMATION,
  74
  75   /**
  76    * Update properties of an address, using
  77    * #GNUNET_ATS_address_update().
  78    */
  79   CMD_UPDATE_ADDRESS,
  80
  81   /**
  82    * Add session to an address, using
  83    * #GNUNET_ATS_address_add_session().
  84    */
  85   CMD_ADD_SESSION,
  86
  87   /**
  88    * Remove session from an address, using
  89    * #GNUNET_ATS_address_del_session().
  90    */
  91   CMD_DEL_SESSION,
  92
  93   /**
  94    * Change performance preferences for a peer, testing
  95    * #GNUNET_ATS_performance_change_preference().
  96    */
  97   CMD_CHANGE_PREFERENCE,
  98
  99   /**
 100    * Provide allocation quality feedback, testing
 101    * #GNUNET_ATS_performance_give_feedback().
 102    */
 103   CMD_PROVIDE_FEEDBACK,
 104
 105   /**
 106    * Obtain list of all addresses, testing
 107    * #GNUNET_ATS_performance_list_addresses().
 108    */
 109   CMD_LIST_ADDRESSES,
 110
 111   /**
 112    * Reserve bandwidth, testing
 113    * #GNUNET_ATS_reserve_bandwidth().
 114    */
 115   CMD_RESERVE_BANDWIDTH,
 116
 117   /**
 118    * Wait for a bit.
 119    */
 120   CMD_SLEEP
 121
 122 };
 123
 124
 125 /**
 126  * Details for the #CMD_ADD_ADDRESS command.
 127  */
 128 struct CommandAddAddress
 129 {
 130   /**
 131    * Number of the peer (used to generate PID).
 132    */
 133   unsigned int pid;
 134
 135   /**
 136    * Number of the address (used to generate binary address).
 137    */
 138   unsigned int addr_num;
 139
 140   /**
 141    * Session to supply, 0 for NULL.
 142    */
 143   unsigned int session;
 144
 145   /**
 146    * Flags to set for the address.
 147    */
 148   enum GNUNET_HELLO_AddressInfo addr_flags;
 149
 150   /**
 151    * Performance properties to supply.
 152    */
 153   struct GNUNET_ATS_Properties properties;
 154
 155   /**
 156    * Expect the operation to fail (duplicate).
 157    */
 158   int expect_fail;
 159
 160   /**
 161    * Here the result of the add address operation will be stored.
 162    */
 163   struct GNUNET_ATS_AddressRecord *ar;
 164 };
 165
 166
 167 /**
 168  * Details for the #CMD_DEL_ADDRESS command.
 169  */
 170 struct CommandDelAddress
 171 {
 172   /**
 173    * Label of the corresponding #CMD_ADD_ADDRESS that
 174    * we are now to remove.
 175    */
 176   const char *add_label;
 177 };
 178
 179
 180 /**
 181  * Details for the #CMD_AWAIT_ADDRESS_SUGGESTION command.
 182  */
 183 struct CommandAwaitAddressSuggestion
 184 {
 185   /**
 186    * For which peer do we expect a suggestion?
 187    */
 188   unsigned int pid;
 189
 190   /**
 191    * If we expect the address suggested to match a particular
 192    * addition, specify the label of the add operation here. Otherwise
 193    * use NULL for "any" available address.
 194    */
 195   const char *add_label;
 196
 197 };
 198
 199
 200 /**
 201  * Details for the #CMD_AWAIT_DISCONNECT_SUGGESTION command.
 202  */
 203 struct CommandAwaitDisconnectSuggestion
 204 {
 205   /**
 206    * For which peer do we expect the disconnect?
 207    */
 208   unsigned int pid;
 209
 210 };
 211
 212
 213 /**
 214  * Details for the #CMD_REQUEST_CONNECTION_START command.
 215  */
 216 struct CommandRequestConnectionStart
 217 {
 218   /**
 219    * Identity of the peer we would like to connect to.
 220    */
 221   unsigned int pid;
 222
 223   /**
 224    * Location where we store the handle returned from
 225    * #GNUNET_ATS_connectivity_suggest().
 226    */
 227   struct GNUNET_ATS_ConnectivitySuggestHandle *csh;
 228 };
 229
 230
 231 /**
 232  * Details for the #CMD_REQUEST_CONNECTION_STOP command.
 233  */
 234 struct CommandRequestConnectionStop
 235 {
 236   /**
 237    * Label of the corresponding #CMD_REQUEST_CONNECTION_START that
 238    * we are now stopping.
 239    */
 240   const char *connect_label;
 241 };
 242
 243
 244 /**
 245  * Details for the #CMD_AWAIT_ADDRESS_INFORMATION command.
 246  */
 247 struct CommandAwaitAddressInformation
 248 {
 249   /**
 250    * For which address do we expect information?
 251    * The address is identified by the respective
 252    * label of the corresponding add operation.
 253    */
 254   const char *add_label;
 255
 256   /**
 257    * Label of a possible update operation that may
 258    * have modified the properties.  NULL to use
 259    * the properties from the @e add_label.
 260    */
 261   const char *update_label;
 262
 263 };
 264
 265
 266 /**
 267  * Details for the #CMD_UPDATE_ADDRESS command.
 268  */
 269 struct CommandUpdateAddress
 270 {
 271   /**
 272    * Label of the addresses's add operation.
 273    */
 274   const char *add_label;
 275
 276   /**
 277    * Performance properties to supply.
 278    */
 279   struct GNUNET_ATS_Properties properties;
 280
 281 };
 282
 283
 284 /**
 285  * Details for the #CMD_ADD_SESSION command.
 286  */
 287 struct CommandAddSession
 288 {
 289  /**
 290    * Label of the addresses's add operation.
 291    */
 292   const char *add_label;
 293
 294   /**
 295    * Session to supply.
 296    */
 297   unsigned int session;
 298
 299 };
 300
 301
 302 /**
 303  * Details for the #CMD_DEL_SESSION command.
 304  */
 305 struct CommandDelSession
 306 {
 307  /**
 308    * Label of the addresses's add operation.
 309    */
 310   const char *add_session_label;
 311
 312 };
 313
 314
 315 /**
 316  * Details for the #CMD_CHANGE_PREFERENCE command.
 317  */
 318 struct CommandChangePreference
 319 {
 320   /**
 321    * Identity of the peer we have a preference change towards.
 322    */
 323   unsigned int pid;
 324
 325   /* FIXME: preference details! */
 326
 327 };
 328
 329
 330 /**
 331  * Details for the #CMD_PROVIDE_FEEDBACK command.
 332  */
 333 struct CommandProvideFeedback
 334 {
 335   /**
 336    * Identity of the peer we have a feedback for.
 337    */
 338   unsigned int pid;
 339
 340   /**
 341    * Over which timeframe does the feedback apply?
 342    */
 343   struct GNUNET_TIME_Relative scope;
 344
 345   /* FIXME: feedback details! */
 346 };
 347
 348
 349 /**
 350  * Details for the #CMD_LIST_ADDRESSES command.
 351  */
 352 struct CommandListAddresses
 353 {
 354   /**
 355    * Identity of the peer we want a list for.
 356    */
 357   unsigned int pid;
 358
 359   /**
 360    * All addresses or just active?
 361    */
 362   int all;
 363
 364   /**
 365    * Minimum number of addresses the callback may report.
 366    */
 367   unsigned int min_calls;
 368
 369   /**
 370    * Maximum number of addresses the callback may report.
 371    */
 372   unsigned int max_calls;
 373
 374   /**
 375    * Minimum number of active addresses the callback may report.
 376    */
 377   unsigned int min_active_calls;
 378
 379   /**
 380    * Maximum number of active addresses the callback may report.
 381    */
 382   unsigned int max_active_calls;
 383
 384   /**
 385    * Number of calls the command invoked the callback with
 386    * an address marked as active. (Set by command).
 387    */
 388   unsigned int active_calls;
 389
 390   /**
 391    * Number of calls the command invoked the callback with
 392    * any address marked as available to ATS. (Set by command).
 393    */
 394   unsigned int calls;
 395
 396   /**
 397    * Location where we store the return value from
 398    * #GNUNET_ATS_performance_list_addresses().
 399    */
 400   struct GNUNET_ATS_AddressListHandle *alh;
 401
 402 };
 403
 404
 405 /**
 406  * Details for the #CMD_RESERVE_BANDWIDTH command.
 407  */
 408 struct CommandReserveBandwidth
 409 {
 410   /**
 411    * For which peer do we reserve bandwidth?
 412    */
 413   unsigned int pid;
 414
 415   /**
 416    * How much should we try to reserve?
 417    */
 418   int32_t amount;
 419
 420   /**
 421    * Should we expect this to work or fail?
 422    * #GNUNET_YES: must work
 423    * #GNUNET_NO: may work or fail
 424    * #GNUNET_SYSERR: must fail
 425    */
 426   int expected_result;
 427
 428   /**
 429    * Location where we store the return value from
 430    * #GNUNET_ATS_reserve_bandwidth().
 431    */
 432   struct GNUNET_ATS_ReservationContext *rc;
 433
 434 };
 435
 436
 437 /**
 438  * Details for the #CMD_SLEEP command.
 439  */
 440 struct CommandSleep
 441 {
 442   /**
 443    * How long should we wait before running the next command?
 444    */
 445   struct GNUNET_TIME_Relative delay;
 446 };
 447
 448
 449 /**
 450  * A command for the test case interpreter.
 451  */
 452 struct Command
 453 {
 454   /**
 455    * Command code to run.
 456    */
 457   enum CommandCode code;
 458
 459   /**
 460    * Commands can be given a label so we can reference them later.
 461    */
 462   const char *label;
 463
 464   /**
 465    * Additional arguments to commands, if any.
 466    */
 467   union {
 468
 469     struct CommandAddAddress add_address;
 470
 471     struct CommandDelAddress del_address;
 472
 473     struct CommandAwaitAddressSuggestion await_address_suggestion;
 474
 475     struct CommandAwaitDisconnectSuggestion await_disconnect_suggestion;
 476
 477     struct CommandRequestConnectionStart request_connection_start;
 478
 479     struct CommandRequestConnectionStop request_connection_stop;
 480
 481     struct CommandAwaitAddressInformation await_address_information;
 482
 483     struct CommandUpdateAddress update_address;
 484
 485     struct CommandAddSession add_session;
 486
 487     struct CommandDelSession del_session;
 488
 489     struct CommandChangePreference change_preference;
 490
 491     struct CommandProvideFeedback provide_feedback;
 492
 493     struct CommandListAddresses list_addresses;
 494
 495     struct CommandReserveBandwidth reserve_bandwidth;
 496
 497     struct CommandSleep sleep;
 498
 499   } details;
 500
 501 };
 502
 503
 504 /**
 505  * Run ATS test.
 506  *
 507  * @param argc length of @a argv
 508  * @param argv command line
 509  * @param cmds commands to run with the interpreter
 510  * @param timeout how long is the test allowed to take?
 511  * @return 0 on success
 512  */
 513 int
 514 TEST_ATS_run (int argc,
 515               char *argv[],
 516               struct Command *cmds,
 517               struct GNUNET_TIME_Relative timeout);
 518
 519 #endif