Developer's Notes

Development Processes and Guidelines

We welcome all contributions to the SCTP kernel reference implementation project and have created the following processes and guidelines to provide a development framework. Also, if you are interested in testing, please refer to the developer's testframe for more information on the testframe used for most of our unit and functional testing.

Architecture

The two key architectural metaphores for LKSCTP are the state machine and the smart pipe. All contributions need to fit sensibly into one or the other metaphore.

The core state machine is side-effect-free (pure functional) with a separate and explicit side-effect processing component. The smart pipes accept raw stuff in one end, and automagically emit cooked pieces out the other end. See the OLS LKSCTP paper for more details.

Coding Guidelines

If you would like to contribute code to the lksctp project, you are strongly encouraged to read the GNU Coding Standards, especially the section entitled "Making The Best Use of C". In addition, please read the Linux Kernel Coding Style document, which is also available in /usr/src/linux/Documentation/CodingStyle. Finally, the file style-guide.txt located in your lksctp source tree docs directory. It contains style guidelines specific to the lksctp project.

Testing is important

Testing is an integral part of the project. Contributors need to provide tests which exercise the new feature/function before submitting code. It is OK to include test cases with a code submission, but it is a lot easier for the developers if you submit the tests first. The tests should compile and fail before your new code is added. This is how we maintain our regression suite.

In the lksctp source tree, testcases are built and run in the test directory. Refer to the section on the developer's testframe for more information.

The Source Code Repository

The lksctp source code repositories are now hosted at BitKeeper to ease interactions with the mainline Linux kernel developers.

The lksctp repostories may be accessed at http://linux-lksctp.bkbits.net/. The lksctp source code is split into two repositories. The lksctp-2.5.work repository holds only the code relevant the the Linux kernel source tree, while the lksctp-tools repository holds user-level code such as libraries, tests, and tools.

Please refer to the BitKeeper for excellent documentation and tutorials for using Bitkeeper.

Build and Install lksctp

Refer to the instructions in the INSTALL document.

Testing lksctp

Reboot your system with the new kernel and follow these steps:

Change to your lksctp-tools source directory, then to the src/func_tests directory.
Type make.

To run the tests currently available for the lksctp, follow these instructions:

Type make v4test. This will build and run a number of SCTP tests against the newly installed kernel via loopback.
If you built and installed the new kernel with IPv6 configured, also run make v6test to verify the IPv6 support in lksctp.

These are the basic regression tests for you to exercise. You may also want to use other test tools available to do more testing. sctp_darn, for example, is a tool which can be used to exercise the SCTP implementation interactively from a user's standpoint. For more information, refer to the section on testing tools.

Developer's Testframe

There are a number of testing tools included in the lksctp releases. One of the tools is a testframe that provides a functional verification testing capability for the project.

The testframe is a minimum dummy kernel environment, in which the lksctp code can be built and run in user mode with specially designed test cases. This testframe provides an easy regressional testing mechanism for developers to verify new code and new functions in lksctp. You can run the frametests using the following steps.

Change to your lksctp-tools source directory, then to the test directory.

Set environment variable "LKSCTP_LINUX" to point to the kernel source tree containing the lksctp source code. For example, export LKSCTP_LINUX="~/bk/lksctp-2.6"
Type make unittest. make unittest builds and runs a number of unit tests against the lksctp code in the source tree.
Type make frametest. make frametest builds and runs a number of functional tests against the lksctp code in the source tree.
If you have IPv6 configured in the kernel source tree, you can also run make frame6 to verify the IPv6 support in lksctp.

As you develop new lksctp code, it is important to generate new test cases to test your code whenever possible. Always make sure that all of the existing test cases run successfully before you make your contributions.

Submitting Contributions

All contributions are accepted in source code patch format. To submit your patch, follow the Linux kernel patch creation instructions available in /usr/src/linux/Documentation/SubmittingPatches. Also, please refer to the Patch list on SourceForge for more information on existing patches. Patches are submitted via the SourceForge patch tool.