idnits 2.17.1 draft-deason-afs3-type-time-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 12, 2011) is 4756 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 N/A A. Deason 3 Internet-Draft Sine Nomine 4 Intended status: Informational April 12, 2011 5 Expires: October 14, 2011 7 Base Types for Time in AFS-3 8 draft-deason-afs3-type-time-01 10 Abstract 12 This document defines two types to be used in future AFS-3 Rx Remote 13 Procedure Calls (RPCs) to represent time. Current AFS-3 RPCs 14 represent time as 32-bit integers representing seconds. This is 15 insufficient in both granularity and range, so new types to represent 16 time are defined in this document to overcome these limitations. 18 Internet Draft Comments 20 Comments regarding this draft are solicited. Please include the 21 AFS-3 protocol standardization mailing list 22 (afs3-standardization@openafs.org) as a recipient of any comments. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on October 14, 2011. 41 Copyright Notice 43 Copyright (c) 2011 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Conventions Used in this Document . . . . . . . . . . . . . . 3 57 3. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3.1. AFSTimestamp . . . . . . . . . . . . . . . . . . . . . . . 4 59 3.2. AFSRelTimestamp . . . . . . . . . . . . . . . . . . . . . 4 60 3.3. AFSTime . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3.3.1. Resolution Assumptions . . . . . . . . . . . . . . . . 6 62 4. Time Resolution . . . . . . . . . . . . . . . . . . . . . . . 6 63 4.1. Sources of Differing Time Resolutions . . . . . . . . . . 6 64 4.2. Relevance to AFS-3 . . . . . . . . . . . . . . . . . . . . 7 65 4.3. When to Include Resolution Information . . . . . . . . . . 7 66 5. Converting Time Types . . . . . . . . . . . . . . . . . . . . 8 67 5.1. Special Cases . . . . . . . . . . . . . . . . . . . . . . 9 68 5.2. Sample Code . . . . . . . . . . . . . . . . . . . . . . . 9 69 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 70 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 71 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 12 72 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 73 9.1. Normative References . . . . . . . . . . . . . . . . . . . 12 74 9.2. Informative References . . . . . . . . . . . . . . . . . . 13 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 77 1. Introduction 79 All extant AFS-3 RPCs represent time as a 32-bit integer, as encoded 80 by XDR in [RFC4506], which represents a number of seconds. For RPCs 81 that specify an absolute time, this is the number of seconds that 82 have passed since since midnight or 0 hour January 1, 1970 83 Coordinated Universal Time (UTC), not counting leap seconds. These 84 time structures will be unusable after January 2038, and are already 85 insufficient to represent time with more granularity than one second. 87 This limited granularity creates inefficiencies in various parts of 88 the AFS-3 protocol when it must be determined in what order two 89 events have occurred (for example, whether or not a file was changed 90 since the last time a volume has been backed up). When those two 91 events have occurred during the same second, implementations must 92 take a conservative assumption about which event occurred first, 93 often resulting in unnecessary duplication or retransmission of data. 94 In addition, metadata can be lost when files are copied to AFS from 95 other filesystems that store file modification times with finer 96 granularity than one second. 98 This document defines three new types to represent time to overcome 99 these limitations: AFSTimestamp, AFSRelTimestamp, and AFSTime. All 100 of these support a much wider time range at a much higher granularity 101 than the current time representations. AFSRelTimestamp is to be used 102 to represent times relative to some other event, and AFSTimestamp is 103 to be used to represent absolute time stamps. AFSTime is to be used 104 to represent a small range of absolute time, which is necessary for 105 determining relative ordering of events, as described in Section 4. 107 All of these new types also have the additional benefit of providing 108 standard type identifiers to be used when specifying absolute or 109 relative time in AFS-3 RPC arguments and structures. Currently, all 110 time values are just defined as "afs_int32" types in the XDR language 111 definitions. This can make it confusing whether or not a field is an 112 absolute time, relative time, or something else completely. Using 113 the new standard time types will make this clear and unambiguous. 115 2. Conventions Used in this Document 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in [RFC2119]. 121 3. Data Types 123 This document defines three new data types: AFSTimestamp, 124 AFSRelTimestamp, and AFSTime. All of these are encoded on the wire 125 using the XDR standard described in [RFC4506], and are described 126 using the XDR language specification therein. 128 3.1. AFSTimestamp 130 The new AFSTimestamp type is represented as an XDR-encoded 64-bit 131 unsigned integer representing the timestamp. It is defined as thus 132 in XDR: 134 typedef unsigned hyper AFSTimestamp; 136 The AFSTimestamp type represents the amount of time that has passed 137 since midnight or 0 hour January 1, 1601 Coordinated Universal Time 138 (UTC). The value represents this amount of time in increments of 100 139 nanoseconds (ns). This precision and starting date is equivalent to 140 the Microsoft Windows FILETIME structure. 142 For example, to represent the time 60 seconds after midnight on 143 January 1, 1601, the value of the field would be 600000000 (600 144 million). 146 This structure can represent any time from January 1, 1601 up to the 147 year 30282 with 100-ns granularity. 149 3.2. AFSRelTimestamp 151 The new AFSRelTimestamp type has nearly the same representation on 152 the wire as AFSTimestamp in Section 3.1: 154 typedef hyper AFSRelTimestamp; 156 The AFSRelTime type represents the amount of time that has passed 157 since some other event. The event to which this time is relative is 158 unspecified, and can be anything; it must be specified by the RPC or 159 structure that defines a field of the AFSRelTime type. 161 The value represents this amount of time in increments of 100 ns. 162 Values greater than 0 represent dates that occur after the relative 163 event, and values less than 0 represent dates that occur before the 164 relative event. 166 For example, to represent the time 5 seconds before some other event, 167 the value of the timestamp field would be -50000000 (negative 50 168 million). 170 3.3. AFSTime 172 The new AFSTime type is represented as an XDR-encoded structure on 173 the wire, containing an AFSTimestamp and a 32-bit unsigned integer 174 representing the resolution. It is defined as thus in XDR: 176 struct AFSTime { 177 AFSTimestamp timestamp; 178 unsigned int resolution; 179 }; 181 The AFSTime structure represents the amount of time that has passed 182 since midnight or 0 hour January 1, 1601 Coordinated Universal Time 183 (UTC). The value of the timestamp field is this amount of time 184 represented as described in Section 3.1. 186 The resolution field represents the resolution of the time source 187 from which the timestamp was obtained. The value of the resolution 188 field is the difference between the represented time, and another 189 time after the represented time that is guaranteed to be after the 190 actual time at which the event in question occurred. 192 In other words, let X be the time that some event occurred, Y be the 193 value of the timestamp field in an AFSTime structure, and Z be the 194 value of the resolution field. To construct an AFSTime structure 195 that represents X, the values of the timestamp and resolution field 196 MUST be specified such that Y <= X < Y + Z. Typically the value of 197 the resolution field will just be the resolution of the time source 198 from which the timestamp was obtained, if the resolution of the time 199 source is constant. 201 For example, to represent the time 60 seconds after midnight on 202 January 1, 1601, the value of the timestamp field would be 600000000 203 (600 million) as described in Section 3.1. If this time stamp was 204 obtained from a source that only represents time in seconds, the next 205 representable time is 61 seconds after midnight on January 1, 1601, 206 so it is guaranteed that the event in question occurred before that 207 time (otherwise the time source would give us a time of 61 seconds). 208 So the value of the resolution field should be 10000000 (10 million). 209 In effect, this AFSTime structure represents an event that occurred 210 at or after 60 seconds after January 1, 1601, but occurred before 61 211 seconds after January 1, 1601. 213 For more details about the resolution field (including the motivation 214 for its existence), see Section 4. 216 3.3.1. Resolution Assumptions 218 If the resolution field has the value of 0, the resolution of the 219 specified timestamp is unknown. If an implementation has absolutely 220 no mechanism to determine the resolution of a time source when 221 creating a time stamp, it MUST specify a resolution of 0. If an 222 implementation needs to use an AFSTime value for calculating event 223 ordering, and the resolution is 0, it SHOULD assume a resolution of 1 224 second, and round the timestamp down to the nearest second. 226 An AFS-3 implementation MUST NOT ever specify a resolution greater 227 than 1 second (10000000 100-ns increments). Implementations of the 228 AFS-3 protocol that exist prior to the introduction of the new time 229 types in this document assume that the time resolution is 1 second, 230 and may not behave correctly with time sources that are less granular 231 than 1 second. No systems nor file formats that are related to any 232 AFS-3 implementation are known that do not have at least 1-second 233 granularity, so adhering to this should not be a problem. 235 If an implementation receives an AFSTime structure with a granularity 236 coarser than 1 second, it MUST treat it as an invalid time 237 representation. What that entails depends on the context, but the 238 AFSTime value MUST NOT be used for any calculations and SHOULD be 239 immediately discarded. Typically an RPC will raise some kind of 240 error in this condition, but the exact behavior is up to the relevant 241 RPC or other operation. 243 4. Time Resolution 245 The new type AFSTime includes information about the resolution or 246 granularity of the time it represents. The reason for including this 247 information may not be immediately clear, so this section provides 248 some information on why this information is beneficial. 250 4.1. Sources of Differing Time Resolutions 252 All current AFS-3 implementations represent time as a 32-bit integer 253 on the wire, and so it is common for implementations to internally 254 represent time as 32-bit integers, with 1-second granularity. As 255 such, when implementations support the time types defined in this 256 document, it is likely that there will be a period of time where 257 implementations cannot store or represent time with greater 258 granularity than 1-second, even though the protocol allows them to do 259 so. 261 In addition, due to technical restrictions of various platforms, or 262 other sources of time (such as file formats), implementations may be 263 only able to transmit time information in certain granularities. For 264 example, the operating system that an AFS-3 Volume Server 265 implementation runs on may only be able to retrieve the current time 266 in increments of 1 millisecond. Or, an AFS-3 Volume Server 267 implementation may be reading the time information from a file, and 268 the file only represents time in increments of 1 second. 270 From this, it is clear that implementations will send time of various 271 granularity when communicating with other services and clients in 272 AFS-3, and the granularity of time may vary even within the same 273 implementation process (depending on from where it is obtaining the 274 time). 276 4.2. Relevance to AFS-3 278 Timestamps are sometimes used in AFS-3 to establish a relative non- 279 strict total ordering of events. That is, given the events X and Y, 280 we must determine whether X or Y occurred first, or if they occurred 281 at approximately the same time. This primarily occurs in volume 282 operations when incremental data is sent, and exactly what 283 incremental data is sent is determined by the timestamps of other 284 volumes. If we get the ordering wrong, problems with data 285 inconsistency can occur. If we conservatively determine that two 286 events occurred at the same time when we could have correctly made 287 the determination that one occurred before the other, inefficiencies 288 arise. 290 In order to be able to order such events, then, we must know the 291 resolution of the time value that is stored. This is so we know the 292 earliest possible time that the event occurred, and the latest 293 possible time that the event occurred. 295 4.3. When to Include Resolution Information 297 There are two time types defined in this document to represent an 298 absolute timestamp: AFSTimestamp and AFSTime. The only difference 299 between these two types is that AFSTime includes resolution 300 information, and AFSTimestamp does not. This section serves to guide 301 designers of future AFS-3 RPCs in what circumstances each type should 302 be used. 304 When deciding whether to use AFSTimestamp or AFSTime in a structure 305 field or RPC argument, the first determination that must be made is 306 whether the timestamp value will or could ever be used to make 307 ordering decisions by an AFS-3 service. If it will or could, then 308 the argument or field should be of the AFSTime type. 310 Otherwise, the determination should be made whether or not any 311 service (possibly unrelated to AFS-3) may realistically make ordering 312 decisions based on the field or argument. If it may, then the 313 AFSTime type should be considered; otherwise, the AFSTimestamp type 314 should be used. 316 For example, as mentioned in Section 4.2, the AFS-3 Volume Service 317 and clients make ordering decisions based on timestamps related to 318 when volume operations have occurred. So, timestamp fields related 319 to volume operations should probably use the AFSTime type. 321 However, when a timestamp is used to represent the modification time 322 of a file in AFS, that timestamp is not used by AFS-3 services to 323 make any ordering decisions. While it is possible that some software 324 unrelated to AFS-3 may try to make ordering decisions based off of 325 that timestamp, it is unlikely to be able to do so reliably. This is 326 because file modification timestamps can usually be set to any time 327 by humans, and any time resolution information stored is usually not 328 available to programs that are not AFS-3-aware. And in general, 329 AFS-3 file metadata is not intended to be a general-purpose 330 distributed synchronization mechanism. So, file modification 331 timestamps should probably use the AFSTimestamp type. 333 5. Converting Time Types 335 In general, when converting an AFSTimestamp or AFSTime value to some 336 other type that has granularity coarser than 100 ns granularity, the 337 resulting value MUST always be rounded down to the nearest lower 338 increment of the resultant type. When converting to the POSIX time_t 339 type, for example, the AFSTimestamp or AFSTime value MUST be rounded 340 down to the nearest lower second. When converting to the POSIX 341 struct timeval type, the value MUST be rounded down to the nearest 342 lower microsecond. 344 POSIX time values are also typically specified in terms of the amount 345 of time that has passed since midnight 1 January 1970 UTC. Since 346 AFSTime and AFSTimestamp times are specified relative to midnight 1 347 January 1601 UTC, an offset must be added or subtracted when 348 converting. When converting from an AFSTimestamp to a POSIX time_t, 349 the value 116444736000000000 should be subtracted from the 350 AFSTimestamp before converting to seconds. Similarly, when 351 converting to an AFSTimestamp value from a POSIX time_t, the value 352 116444736000000000 should be added after converting to 100 ns 353 increments. 355 When converting to or from a Microsoft FILETIME structure, the values 356 can be simply copied, as the granularity and starting date are the 357 same. 359 It is also important to keep in mind that when converting from 360 AFSTime to time_t or FILETIME types, strictly speaking the AFSTime 361 structure represents two times: the beginning and end time. So it is 362 impossible to accurately convert an AFSTime structure to a single 363 time value. This is often unavoidable when converting to legacy 364 AFS-3 interfaces, or interfaces unrelated to AFS-3, however, and when 365 only one time value is given to convert to, implementations MUST 366 specify the beginning time (that is, the time represented by the 367 timestamp field). 369 5.1. Special Cases 371 Extant AFS-3 RPCs often use a timestamp of 0 to represent a special 372 meaning. That is, a timestamp of 0 often does not indicate midnight 373 1 January 1970 UTC, but may represent a logical value of "negative 374 infinity", or indicates some special meaning that is specific to that 375 RPC. The value of 0 was often just used because it is the earliest 376 representable time for a 32-bit unsigned integer. 378 Any such special meanings must be specified by the RPC in question, 379 and this document assigns no special meaning to the value of 0 for 380 any of the types defined in this document. However, this document 381 recommends that any future RPCs keep the special meaning of the 0 382 timestamp, if the RPC is replacing an RPC that previously had a 383 special meaning for timestamp 0. If the new RPC uses an AFSTime 384 argument, the resolution field should be 0, as well. 386 For example, say there is an AFS-3 RPC called AFSFoo that accepts an 387 afs_uint32 absolute timestamp argument, and it specifies that a 388 timestamp of 0 represents some special case. Let another RPC, 389 AFSFoo64, define an RPC that is identical to AFSFoo except that it 390 accepts an AFSTime parameter. AFSFoo64 should specify that a caller 391 should specify an AFSTime with timestamp 0, resolution 0, to indicate 392 the special case previously indicated by giving a 32-bit timestamp of 393 0, even though those represent two different times. 395 5.2. Sample Code 397 Sample C code is provided here to convert AFSTimestamp, 398 AFSRelTimestamp, and AFSTime values to and from FILETIME and POSIX 399 time_t values where appropriate. Also provided is a function to 400 compare two AFSTime values, and functions to add an AFSRelTimestamp 401 to an AFSTime and AFSTimestamp. 403 The conversion functions assume that the special cases described in 404 Section 5.1 are relevant. So, a time_t with the value of 0 will be 405 converted to an AFSTimestamp with the value of 0, or an AFSTime value 406 of timestamp 0, resolution 0, instead of converting to the value that 407 represents midnight 1 Jan 1970. AFSTime structures with a resolution 408 of 0 (and a non-zero timestamp) are treated as having an effective 409 resolution of 1 second, as suggested in Section 3.3.1. 411 These functions do not handle overflow, underflow, or other errors, 412 and are just guidelines for the general conversion algorithms. 414 #define AFSTIME_POSIX_SHIFT 116444736000000000ULL 415 #define AFSTIME_POSIX_SCALE 10000000U 416 #define AFSTIME_DEFAULT_RES 10000000U 418 void 419 timet_to_AFSTimestamp(time_t t, AFSTimestamp *atsp) 420 { 421 if (t == 0) { 422 *atsp = 0; 423 } else { 424 *atsp = (t * AFSTIME_POSIX_SCALE) + AFSTIME_POSIX_SHIFT; 425 } 426 } 427 void 428 AFSTimestamp_to_timet(AFSTimestamp ats, time_t *tp) 429 { 430 if (ats == 0) { 431 *tp = 0; 432 } else { 433 *tp = ((ats - AFSTIME_POSIX_SHIFT) / AFSTIME_POSIX_SCALE); 434 } 435 } 436 void 437 timet_to_AFSRelTimestamp(time_t t, AFSRelTimestamp *artsp) 438 { 439 *artsp = (t * AFSTIME_POSIX_SCALE); 440 } 441 void 442 AFSRelTimestamp_to_timet(AFSRelTimestamp arts, time_t *tp) 443 { 444 *tp = (arts / AFSTIME_POSIX_SCALE); 445 } 446 void 447 timet_to_AFSTime(time_t t, AFSTime *atp) 448 { 449 timet_to_AFSTimestamp(t, &atp->timestamp); 450 if (t == 0) { 451 atp->resolution = 0; 452 } else { 453 atp->resolution = AFSTIME_POSIX_SCALE; 454 } 456 } 457 void 458 AFSTime_to_timet(AFSTime *atp, time_t *t1, time_t *t2) 459 { 460 unsigned int res = atp->resolution; 461 if (res == 0) { 462 res = AFSTIME_DEFAULT_RES; 463 } 464 AFSTimestamp_to_timet(atp->timestamp, t1); 465 AFSTimestamp_to_timet(atp->timestamp + res, t2); 466 } 467 void 468 FILETIME_to_AFSTimestamp(FILETIME *ftp, AFSTimestamp *atsp) 469 { 470 ULARGE_INTEGER uli; 471 uli.LowPart = ftp->dwLowDateTime; 472 uli.HighPart = ftp->dwHighDateTime; 473 *atsp = uli.QuadPart; 474 } 475 void 476 AFSTimestamp_to_FILETIME(AFSTimestamp ats, FILETIME *ftp) 477 { 478 ULARGE_INTEGER uli; 479 uli.QuadPart = ats; 480 ftp->dwLowDateTime = uli.LowPart; 481 ftp->dwHighDateTime = uli.HighPart; 482 } 483 void 484 AFSTime_to_FILETIME(AFSTime *atp, FILETIME *ft1, FILETIME *ft2) 485 { 486 unsigned int res = atp->resolution; 487 if (res == 0) { 488 res = AFSTIME_DEFAULT_RES; 489 } 490 AFSTimestamp_to_FILEMTIME(atp->timestamp, ft1); 491 AFSTimestamp_to_FILEMTIME(atp->timestamp + res, ft2); 492 } 493 void 494 AFSTime_add_AFSRelTimestamp(AFSTime *atp, AFSRelTimestamp arts) 495 { 496 atp->timestamp += arts; 497 } 498 void 499 AFSTimestamp_add_AFSRelTimestamp(AFSTimestamp *atsp, 500 AFSRelTimestamp arts) 501 { 502 *atsp += arts; 503 } 504 int 505 cmp_AFSTime(AFSTime *atp1, AFSTime *atp2) 506 { 507 unsigned int res1 = atp1->resolution; 508 unsigned int res2 = atp2->resolution; 509 if (res1 == 0) { 510 res1 = AFSTIME_DEFAULT_RES; 511 } 512 if (res2 == 0) { 513 res2 = AFSTIME_DEFAULT_RES; 514 } 515 if (atp1->timestamp + res1 <= atp2->timestamp) { 516 return -1; 517 } 518 if (atp2->timestamp + res2 <= atp1->timestamp) { 519 return 1; 520 } 521 return 0; 522 } 524 6. Security Considerations 526 This memo raises no security issues. 528 7. IANA Considerations 530 This document makes no request of the IANA. 532 8. Acknowledgements 534 The author thanks Simon Wilkinson and Jeffrey Altman for some 535 background text, and Jeffrey Altman, David Boyes, Tom Keiser, and 536 Simon Wilkinson for discussion on the problem of time resolution. 538 9. References 540 9.1. Normative References 542 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 543 Requirement Levels", BCP 14, RFC 2119, March 1997. 545 9.2. Informative References 547 [RFC4506] Eisler, M., "XDR: External Data Representation Standard", 548 STD 67, RFC 4506, May 2006. 550 Author's Address 552 Andrew Deason 553 Sine Nomine Associates 554 43596 Blacksmith Square 555 Ashburn, Virginia 20147-4606 556 USA 558 Phone: +1 703 723 6673 559 Email: adeason@sinenomine.net