2 This file is part of GNUnet.
3 (C) 2010,2011 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
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 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
21 * @file include/gnunet_ats_service.h
22 * @brief automatic transport selection and outbound bandwidth determination
23 * @author Christian Grothoff
24 * @author Matthias Wachs
26 #ifndef GNUNET_ATS_SERVICE_H
27 #define GNUNET_ATS_SERVICE_H
29 #include "gnunet_constants.h"
30 #include "gnunet_util_lib.h"
31 #include "gnunet_hello_lib.h"
34 enum GNUNET_ATS_Network_Type
36 GNUNET_ATS_NET_UNSPECIFIED,
37 GNUNET_ATS_NET_LOOPBACK,
43 * Enum defining all known property types for ATS Enum values are used
44 * in the GNUNET_ATS_Information struct as
47 * Cost are always stored in uint32_t, so all units used to define costs
48 * have to be normalized to fit in uint32_t [0 .. 4.294.967.295]
50 enum GNUNET_ATS_Property
57 GNUNET_ATS_ARRAY_TERMINATOR = 0,
60 * Actual traffic on this connection from the other peer to this peer.
62 * Unit: [bytes/second]
64 GNUNET_ATS_UTILIZATION_UP,
67 * Actual traffic on this connection from this peer to the other peer.
69 * Unit: [bytes/second]
71 GNUNET_ATS_UTILIZATION_DOWN,
74 * Is this address located in WAN, LAN or a loopback address
75 * Value is element of GNUNET_ATS_Network_Type
77 GNUNET_ATS_NETWORK_TYPE,
81 * Time between when the time packet is sent and the packet arrives
91 GNUNET_ATS_QUALITY_NET_DELAY,
94 * Distance on network layer (required for distance-vector routing).
98 GNUNET_ATS_QUALITY_NET_DISTANCE,
101 * Network overhead on WAN (Wide-Area Network)
103 * How many bytes are sent on the WAN when 1 kilobyte (1024 bytes)
104 * of application data is transmitted?
105 * A factor used with connect cost, bandwidth cost and energy cost
106 * to describe the overhead produced by the transport protocol
110 * Interpretation: less is better
114 * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
115 * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
116 * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8 = 1090 [bytes/kb]
117 * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8 = 1110 [bytes/kb]
122 * Network overhead on LAN (Local-Area Network)
124 * How many bytes are sent on the LAN when 1 kilobyte (1024 bytes)
125 * of application data is transmitted?
126 * A factor used with connect cost, bandwidth cost and energy cost
127 * to describe the overhead produced by the transport protocol
131 * Interpretation: less is better
135 * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
136 * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
137 * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8 = 1090 [bytes/kb]
138 * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8 = 1110 [bytes/kb]
143 * Network overhead on WLAN (Wireless Local Area Network)
145 * How many bytes are sent on the LAN when 1 kilobyte (1024 bytes)
146 * of application data is transmitted?
147 * A factor used with connect cost, bandwidth cost and energy cost
148 * to describe the overhead produced by the transport protocol
152 * Interpretation: less is better
156 * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
157 * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
158 * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8 = 1090 [bytes/kb]
159 * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8 = 1110 [bytes/kb]
162 /* Cost related values */
163 /* =================== */
165 * Volume based cost in financial units to transmit data
167 * Note: This value is not bound to a specific currency or unit and only
169 * "cent" just refers the smallest amount of money in the respective
174 * Interpretation: less is better
180 // GNUNET_ATS_COST_FINANCIAL_PER_VOLUME = 1,
182 * Time based cost in financial units to transmit data
184 * Note: This value is not bound to a specific currency or unit and only
186 * "cent" just refers the smallest amount of money in the respective
191 * Interpretation: less is better
195 * Dialup: 10 [cent/h]
197 // GNUNET_ATS_COST_FINANCIAL_PER_TIME = 2,
199 * Computational costs
201 * Effort of preparing data to be sent with this transport
202 * Includes encoding, encryption and conversion of data
203 * Partial values can be summed up: c_sum = c_enc + c_enc + c_conv
204 * Resulting values depend on local system properties, e.g. CPU
208 * Interpretation: less is better
212 * HTTPS with AES CBC-256: 7,382
213 * HTTPS with AES CBC-128: 5,279
214 * HTTPS with RC4-1024: 2,652
216 // GNUNET_ATS_COST_COMPUTATIONAL = 3,
220 * Energy consumption using this transport when sending with a certain
221 * power at a certain bitrate. This is only an approximation based on:
222 * Energy consumption E = P / D
225 * Power P in Watt (J/s)
226 * Datarate D in MBit/s
228 * Conversion between power P and dBm used by WLAN in radiotap's dBm TX power:
230 * Lp(dbm) = 10 log10 (P/ 1mW)
232 * => P = 1 mW * 10^(Lp(dbm)/10)
236 * Interpretation: less is better
241 * WLAN: 89 (600 mW @ 802.11g /w 54 MBit/s)
242 * Bluetooth: 267 (100 mW @ BT2.0 EDR /w 3 MBit/s)
244 // GNUNET_ATS_COST_ENERGY_CONSUMPTION = 4,
247 * How many bytes are transmitted to initiate a new connection using
252 * Interpretation: less is better
256 * UDP (No connection) :
258 * TCP (TCP 3-Way handshake):
259 * 220 bytes Ethernet, 172 bytes TCP/IP, 122 bytes TCP
260 * HTTP (TCP + Header) :
261 * 477 bytes Ethernet, 429 bytes TCP/IP, 374 bytes TCP, 278 bytes HTTP
262 * HTTPS HTTP+TLS Handshake:
263 * 2129 bytes Ethernet, 1975 bytes TCP/IP, 1755 bytes TCP, 1403 bytes HTTPS
266 // GNUNET_ATS_COST_CONNECT = 5,
270 * How many bandwidth is available to consume?
271 * Used to calculate which impact sending data with this transport has
275 * Interpretation: more is better
278 * LAN: 12,800 (100 MBit/s)
279 * WLAN: 6,912 (54 MBit/s)
280 * Dial-up: 8 (64 Kbit/s)
283 // GNUNET_ATS_COST_BANDWITH_AVAILABLE = 6,
287 * How many bytes are sent over the wire when 1 kilobyte (1024 bytes)
288 * of application data is transmitted?
289 * A factor used with connect cost, bandwidth cost and energy cost
290 * to describe the overhead produced by the transport protocol
294 * Interpretation: less is better
298 * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
299 * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
300 * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8 = 1090 [bytes/kb]
301 * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8 = 1110 [bytes/kb]
303 // GNUNET_ATS_COST_NETWORK_OVERHEAD = 7,
304 /* Quality related values */
305 /* ====================== */
306 /* Physical layer quality properties */
308 * Signal strength on physical layer
312 // GNUNET_ATS_QUALITY_PHY_SIGNAL_STRENGTH = 1025,
314 * Collision rate on physical layer
318 // GNUNET_ATS_QUALITY_PHY_COLLISION_RATE = 1026,
320 * Error rate on physical layer
324 // GNUNET_ATS_QUALITY_PHY_ERROR_RATE = 1027,
327 * Time variations of the delay
328 * 1st derivative of a delay function
332 // GNUNET_ATS_QUALITY_NET_JITTER = 1029,
334 * Error rate on network layer
343 * Note: This numbers are just assumptions as an example, not
344 * measured or somehow determined
346 // GNUNET_ATS_QUALITY_NET_ERRORRATE = 1030,
348 * Drop rate on network layer
349 * Bytes actively dismissed by a network component during transmission
350 * Reasons for dropped data can be full queues, congestion, quota violations...
359 * Note: This numbers are just assumptions as an example, not
360 * measured or somehow determined
362 // GNUNET_ATS_QUALITY_NET_DROPRATE = 1031,
364 * Loss rate on network layer
365 * Bytes lost during transmission
366 * Reasons can be collisions, ...
375 * Note: This numbers are just assumptions as an example, not measured
376 * or somehow determined
378 // GNUNET_ATS_QUALITY_NET_LOSSRATE = 1032,
380 * Throughput on network layer
391 // GNUNET_ATS_QUALITY_NET_THROUGHPUT = 1033,
392 /* Availability related values */
393 /* =========================== */
395 * Is a peer reachable?
397 // GNUNET_ATS_AVAILABILITY_REACHABLE = 2048,
399 * Is there a connection established to a peer using this transport
401 // GNUNET_ATS_AVAILABILITY_CONNECTED = 2049
406 * struct used to communicate the transport's properties like cost and
407 * quality of service as well as high-level constraints on resource
411 * +-----------+ Constraints | | Plugin properties +---------+
412 * | Highlevel |------------> |ATS| <------------------|Transport|
413 * | Component | ATS struct | | ATS struct | Plugin |
414 * +-----------+ | | +---------+
417 * This structure will be used by transport plugins to communicate
418 * costs to ATS or by higher level components to tell ATS their
419 * constraints. Always a pair of (GNUNET_ATS_Property,
420 * uint32_t value). Value is always uint32_t, so all units used to
421 * define costs have to be normalized to fit uint32_t.
423 struct GNUNET_ATS_Information
426 * ATS property type, in network byte order.
428 uint32_t type GNUNET_PACKED;
431 * ATS property value, in network byte order.
433 uint32_t value GNUNET_PACKED;
438 /* ******************************** Scheduling API ***************************** */
441 * Handle to the ATS subsystem for bandwidth/transport scheduling information.
443 struct GNUNET_ATS_SchedulingHandle;
447 * Opaque session handle, defined by plugins. Contents not known to ATS.
453 * Signature of a function called by ATS with the current bandwidth
454 * and address preferences as determined by ATS.
457 * @param address suggested address (including peer identity of the peer)
458 * @param session session to use
459 * @param bandwidth_out assigned outbound bandwidth for the connection
460 * @param bandwidth_in assigned inbound bandwidth for the connection
461 * @param ats performance data for the address (as far as known)
462 * @param ats_count number of performance records in 'ats'
464 typedef void (*GNUNET_ATS_AddressSuggestionCallback) (void *cls,
466 GNUNET_HELLO_Address *
468 struct Session * session,
470 GNUNET_BANDWIDTH_Value32NBO
473 GNUNET_BANDWIDTH_Value32NBO
476 GNUNET_ATS_Information *
477 ats, uint32_t ats_count);
481 * Initialize the ATS subsystem.
483 * @param cfg configuration to use
484 * @param suggest_cb notification to call whenever the suggestation changed
485 * @param suggest_cb_cls closure for 'suggest_cb'
486 * @return ats context
488 struct GNUNET_ATS_SchedulingHandle *
489 GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
490 GNUNET_ATS_AddressSuggestionCallback suggest_cb,
491 void *suggest_cb_cls);
495 * Client is done with ATS scheduling, release resources.
497 * @param sh handle to release
500 GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
504 * We would like to establish a new connection with a peer. ATS
505 * should suggest a good address to begin with.
508 * @param peer identity of the peer we need an address for
511 GNUNET_ATS_suggest_address (struct GNUNET_ATS_SchedulingHandle *sh,
512 const struct GNUNET_PeerIdentity *peer);
516 * We want to cancel ATS suggesting addresses for a peer.
519 * @param peer identity of the peer
522 GNUNET_ATS_suggest_address_cancel (struct GNUNET_ATS_SchedulingHandle *sh,
523 const struct GNUNET_PeerIdentity *peer);
526 * We have updated performance statistics for a given address. Note
527 * that this function can be called for addresses that are currently
528 * in use as well as addresses that are valid but not actively in use.
529 * Furthermore, the peer may not even be connected to us right now (in
530 * which case the call may be ignored or the information may be stored
531 * for later use). Update bandwidth assignments.
534 * @param address updated address
535 * @param session session handle (if available)
536 * @param ats performance data for the address
537 * @param ats_count number of performance records in 'ats'
540 GNUNET_ATS_address_update (struct GNUNET_ATS_SchedulingHandle *sh,
541 const struct GNUNET_HELLO_Address *address,
542 struct Session *session,
543 const struct GNUNET_ATS_Information *ats,
548 * An address is now in use or not used any more.
551 * @param address the address
552 * @param session session handle
553 * @param in_use GNUNET_YES if this address is now used, GNUNET_NO
554 * if address is not used any more
557 GNUNET_ATS_address_in_use (struct GNUNET_ATS_SchedulingHandle *sh,
558 const struct GNUNET_HELLO_Address *address,
559 struct Session *session, int in_use);
562 * A session got destroyed, stop including it as a valid address.
565 * @param address the address
566 * @param session session handle that is no longer valid (if available)
569 GNUNET_ATS_address_destroyed (struct GNUNET_ATS_SchedulingHandle *sh,
570 const struct GNUNET_HELLO_Address *address,
571 struct Session *session);
574 /* ******************************** Performance API ***************************** */
577 * ATS Handle to obtain and/or modify performance information.
579 struct GNUNET_ATS_PerformanceHandle;
583 * Signature of a function that is called with QoS information about a peer.
586 * @param address the address
587 * @param bandwidth_out assigned outbound bandwidth for the connection
588 * @param bandwidth_in assigned inbound bandwidth for the connection
589 * @param ats performance data for the address (as far as known)
590 * @param ats_count number of performance records in 'ats'
592 typedef void (*GNUNET_ATS_PeerInformationCallback) (void *cls,
594 GNUNET_HELLO_Address *
597 GNUNET_BANDWIDTH_Value32NBO
600 GNUNET_BANDWIDTH_Value32NBO
603 GNUNET_ATS_Information *
604 ats, uint32_t ats_count);
608 * Get handle to access performance API of the ATS subsystem.
610 * @param cfg configuration to use
611 * @param infocb function to call on performance changes, can be NULL
612 * @param infocb_cls closure for infocb
613 * @return ats performance context
615 struct GNUNET_ATS_PerformanceHandle *
616 GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
617 GNUNET_ATS_PeerInformationCallback infocb,
622 * Client is done using the ATS performance subsystem, release resources.
627 GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph);
631 * Function called with reservation result.
634 * @param peer identifies the peer
635 * @param amount set to the amount that was actually reserved or unreserved;
636 * either the full requested amount or zero (no partial reservations)
637 * @param res_delay if the reservation could not be satisfied (amount was 0), how
638 * long should the client wait until re-trying?
640 typedef void (*GNUNET_ATS_ReservationCallback) (void *cls,
641 const struct GNUNET_PeerIdentity
642 * peer, int32_t amount,
643 struct GNUNET_TIME_Relative
649 * Context that can be used to cancel a peer information request.
651 struct GNUNET_ATS_ReservationContext;
655 * Reserve inbound bandwidth from the given peer. ATS will look at
656 * the current amount of traffic we receive from the peer and ensure
657 * that the peer could add 'amount' of data to its stream.
659 * @param ph performance handle
660 * @param peer identifies the peer
661 * @param amount reserve N bytes for receiving, negative
662 * amounts can be used to undo a (recent) reservation;
663 * @param rcb function to call with the resulting reservation information
664 * @param rcb_cls closure for info
665 * @return NULL on error
666 * @deprecated will be replaced soon
668 struct GNUNET_ATS_ReservationContext *
669 GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph,
670 const struct GNUNET_PeerIdentity *peer,
672 GNUNET_ATS_ReservationCallback rcb,
677 * Cancel request for reserving bandwidth.
679 * @param rc context returned by the original GNUNET_ATS_reserve_bandwidth call
682 GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc);
687 * Enum defining all known preference categories.
689 enum GNUNET_ATS_PreferenceKind
693 * End of preference list.
695 GNUNET_ATS_PREFERENCE_END = 0,
698 * Change the peer's bandwidth value (value per byte of bandwidth in
699 * the goal function) to the given amount. The argument is followed
700 * by a double value giving the desired value (can be negative).
701 * Preference changes are forgotten if peers disconnect.
703 GNUNET_ATS_PREFERENCE_BANDWIDTH,
706 * Change the peer's latency value to the given amount. The
707 * argument is followed by a double value giving the desired value
708 * (can be negative). The absolute score in the goal function is
709 * the inverse of the latency in ms (minimum: 1 ms) multiplied by
710 * the latency preferences.
712 GNUNET_ATS_PREFERENCE_LATENCY
717 * Change preferences for the given peer. Preference changes are forgotten if peers
720 * @param ph performance handle
721 * @param peer identifies the peer
722 * @param ... 0-terminated specification of the desired changes
725 GNUNET_ATS_change_preference (struct GNUNET_ATS_PerformanceHandle *ph,
726 const struct GNUNET_PeerIdentity *peer, ...);
731 /* end of file gnunet-service-transport_ats.h */