README

   1 (C) Copyright 2007 Hewlett-Packard Development Company, L.P.
   2 (C) Copyright IBM Corp. 2001, 2003
   3 Copyright 2001 Motorola, Cisco, Intel, Nokia, La Monte Yarroll.
   4 Copyright 2002 Nokia, La Monte Yarroll, Intel.
   5
   6 This is the lksctp-tools package for Linux Kernel SCTP Reference
   7 Implementation.
   8
   9 This package is intended to supplement the Linux Kernel SCTP
  10 Reference Implementation now available in the Linux kernel source
  11 tree in versions  2.5.36 and following.  For more information on LKSCTP
  12 see the below section titled "LKSCTP - Linux Kernel SCTP."
  13
  14 lksctp-tools
  15 ____________
  16
  17 The lksctp-tools package is intended for two audiences.
  18         1) SCTP application developers
  19         2) LKSCTP project developers
  20
  21 For SCTP application developers, this package provides the user-level
  22 C language header files and a library for accessing SCTP specific
  23 application programming interfaces not provided by the standard sockets.
  24
  25 For LKSCTP project developers, this package provides the API
  26 regression and functional tests.  Developers should also check
  27 lksctp_tests package that provides low level kernel tests.  These
  28 are available from git.kernel.org.
  29
  30 For either role, this project provides sample code, utilities, and
  31 tests that one may find useful.
  32
  33
  34 LKSCTP - Linux Kernel SCTP
  35 __________________________
  36
  37 The Linux Kernel SCTP Reference Implementation is free software; you
  38 can redistribute it and/or modify it under the terms of the GNU
  39 General Public License as published by the Free Software Foundation;
  40 either version 2, or (at your option) any later version. For more
  41 information on licensing terms, please see the file COPYING in this
  42 directory.
  43
  44 SCTP (Stream Control Transmission Protocol) is a message oriented,
  45 reliable transport protocol, with congestion control, support for
  46 transparent multi-homing, and multiple ordered streams of messages.
  47 RFC2960 defines the core protocol. The IETF SIGTRAN Working Group
  48 developed SCTP.  The primary architects are Randy Stewart and Qiaobing
  49 Xie.
  50
  51 The Kernel Reference is first and foremost an exposition of
  52 RFC2960 and related documents. You will find that the comments and
  53 variable names tie closely back to the RFC and Internet Drafts.
  54
  55 This work was started by a small team of developers at Motorola.
  56 Throughout this document, "we" refers to that team.  We intend for the
  57 meaning of "we" to expand to include the whole development community,
  58 all 27 million programmers on the planet.
  59
  60 The Kernel Reference has loose origins in the SCTP User Space Reference
  61 by Randy Stewart and Qiaobing Xie.
  62
  63 MANIFEST
  64 --------
  65 .
  66 |-- bin
  67 |-- doc
  68 |-- man
  69 |-- src
  70     |-- apps
  71     |-- func_tests
  72     |-- include
  73     |   `-- netinet
  74     |-- lib
  75     |-- testlib
  76     `-- withsctp
  77
  78 You may want to check the following files:
  79
  80 COPYING.lib     Licensing terms of libsctp
  81 COPYING         Licensing terms of other pieces of the package
  82 ROADMAP         A tour around the files in the distribution of SCTP-tools.
  83 INSTALL         How to install and run this beast.
  84 ChangeLog       What has changed since the last release?
  85
  86 DESIGN GOALS
  87 ------------
  88
  89 - A primary design goal is to reflect RFC 2960 as closely as
  90 practical.  We have changed many names from the user space reference to
  91 follow the draft as closely as possible.  We have also included
  92 extensive quotes from the draft adjacent to the code which implements
  93 them.
  94
  95 - The other primary design goal is to integrate Linux kernel data
  96 structures and idioms as much as possible.  The test framework (in
  97 directory test/) provides many of the functions which would otherwise
  98 come from the kernel.  The test frame does use libc features, but the
  99 state machine code should be libc-free.
 100
 101 - A lesser design goal is to completely describe the actions for each
 102 state transition in an sctp_command_t (see sctp_command.h).  This
 103 means that the state functions (sctp_state_fn_t in sctp_sm.h) are NOT
 104 allowed to modify their endpoint, association, or chunk arguments.
 105 This is enforced by const modifiers--please respect the compiler
 106 warnings.  All actions must be described in the last argument to the
 107 state function.
 108
 109 - A byte order convention for dealing with the SCTP chunk headers:
 110 all SCTP chunks, regardless if the chunk is to be sent outbound
 111 to the network or was received inbound from the network, the header portion
 112 of the chunk is ALWAYS created and retained in the NETWORK BYTE ORDER.
 113
 114 - An error code handling convention is to return negative values internally.
 115 The sk->err field holds a positive valued errno values, so will need our
 116 internal values negated.
 117
 118 - We are moving toward an XP development model.  So far we have
 119 adopted pair-programming, coding-to-test (functional and unit), design
 120 through refactoring, and story-based planning.
 121
 122 In order to make XP work, it is very important that we have a complete
 123 set of tests for the code.  We can not safely refactor major parts of
 124 the code without a way to find the things we break.  If you decide to
 125 extend the SCTP Kernel Implementation we ask that you do the following:
 126
 127         1) Pick an XP story.  Tell lksctp-developers@lists.sourceforge.net
 128         2) Write a functional test for that XP story.  The functional
 129            test defines "DONE" for the story.
 130         3) Submit the functional test as a patch on SourceForge.
 131         4) Write unit tests for any new "objects" you define.
 132         5) Implement your feature.
 133         6) Submit the feature and the unit tests as a separate
 134         SourceForge patch.
 135
 136 Look in src/func_tests and in lksctp-tests package for examples of of tests.
 137 Please do not submit code that fails its own tests or any of the unit tests.
 138 If it fails a functional test, please document that with the submission.
 139
 140 Another XP requirement is to code only what is you need to make the
 141 current test work.  Where this means omitting required features, we
 142 have put in prominent BUG comments describing the omitted
 143 functionality.
 144
 145 FEATURES
 146 --------
 147 This implementation uses a fairly compact cookie which is isolated in
 148 its own substructure of SCTP_association.  We have been moving toward
 149 aggregating data elements which need to travel together to minimize
 150 copying of individual elements in favour of more efficient structure
 151 copies.
 152
 153 You will find what we believe to be the smallest possible Internet
 154 simulator in the middle of the function test_kernel.c:simulate_internet().
 155 The simulator makes a few simplifying assumptions...
 156
 157 MAILING LISTS and WEB SITES
 158 ---------------------------
 159 http://www.sourceforge.net/projects/lksctp
 160
 161         This is the lksctp project webpage.
 162
 163 lksctp-developers@lists.sourceforge.net
 164
 165         This is the discussion list for developers.  Join this list if
 166         you are interested in following the day-to-day activities of
 167         the SCTP Kernel Reference Implementation development community.
 168         See subscription directions at:
 169                 http://lists.sourceforge.net/lists/listinfo/lksctp-developers
 170
 171 http://www.sctp.org
 172
 173         This is Randy Stewart's SCTP web site.
 174
 175 http://sctp.de
 176
 177         This is Michael Tuexen's SCTP web site.  Michael has collected
 178         dozens of documents related to SCTP.