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