diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index 144e6c3394..f624df6b82 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -324,7 +324,12 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = . midi midi2 ../../headers/os/midi2 +# General documentations and extern documentation files +INPUT = . midi midi2 ppp ../../headers/os/midi2 + +# PPP +INPUT += ../../src/add-ons/kernel/network/ppp/shared/libkernelppp ../../src/add-ons/kernel/network/ppp/shared/libkernelppp/headers +INPUT += ../../src/add-ons/kernel/network/ppp/shared/libppp ../../src/add-ons/kernel/network/ppp/shared/libppp/headers # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp @@ -356,7 +361,7 @@ EXCLUDE_SYMLINKS = NO # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = */libkernelppp/_KPPP* # The EXAMPLE_PATH tag can be used to specify one or more files or # directories that contain example code fragments that are included (see diff --git a/docs/user/book.dox b/docs/user/book.dox index dcfa514ac3..3b9f78f467 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -5,4 +5,5 @@ - \ref midi1 - \ref midi2 +- \ref ppp */ diff --git a/docs/user/ppp/KernelPPPIntro.dox b/docs/user/ppp/KernelPPPIntro.dox new file mode 100644 index 0000000000..c3f5810f42 --- /dev/null +++ b/docs/user/ppp/KernelPPPIntro.dox @@ -0,0 +1,66 @@ +/*! +\page kernelppp The Kernel PPP Kit (libkernelppp.a) + +The PPP stack is a kernel module that interfaces with the network stack. +Thanks to its modular nature new protocols and extensions can be added without +having to recompile the PPP stack. + +The kernel API is mostly intended for developers who want to write extension modules, +but you can also create and control PPP interfaces from within your kernel module. + +Every instance of a PPP interface initially consists of the following classes: + +- KPPPInterface (the main interface class) +- KPPPLCP (the Link Control Protocol) +- KPPPStateMachine (the state machine for the Link Control Protocol) +- KPPPProfile (this manages the current interface profile) + +KPPPLCP, KPPPStateMachine, and KPPPProfile are integrated into KPPPInterface as +member variables. All these classes have private constructors. Only the PPP +interface manager can create a new instance of KPPPInterface. \n +Such an interface does nothing useful because it needs at least a device to connect +to a PPP server. \n +These are the base classes for extending an interface: + +- KPPPDevice (a PPP transport device: PPPoE, modem, cell phone, etc.) +- KPPPLCPExtension (adds new basic codes to the LCP protocol) +- KPPPOptionHandler (adds new configure-packet types to the LCP protocol) +- KPPPProtocol (a base class for protocols; e.g.: LCP and IPCP) + +\section kppppackethandling Packet handling + +KPPPInterface, KPPPDevice, and KPPPProtocol derive from KPPPLayer. When sending, +packets are passed down the stack to every layer that can handle the packet. +This facilitates creating packet encapsulators like compression protocols. You can +even catch packets before they arrive at the device layer. \n +A different system is used for receiving packets: KPPPDevice passes the received +packet to KPPPInterface which in turn tries to find the best fitting KPPPProtocol +that can handle this kind of packet. If one is found it may pass the packet to the +netstack or, in case of an encapsulator, it can put the packet back into the decode +queue by calling KPPPInterface::Receive(). + +\section kpppmultilink Multilink interfaces + +Interfaces can have one parent and multiple children. The first interface of a +multilink bundle is split into a parent and a child. All other children must be added +to the parent when they are needed. Normally, a bundle (main) interface has no parent +and a sub-interface (child) has no children. \n +A multilink protocol can use any desired technique for creating the additional +children. For instance, it could save the descriptions of all children as private +parameters in the interface description file. Alternatively, it could use internal +bundle names to bundle all interfaces with the equal bundle names. \n +If a received packet could not be handled by a child it is passed up to the parent. +On the other hand, an interface without a device (no next layer after the interface) +will \e not pass the packet to its children. + +\section kpppwritingmodules Writing modules + +PPP makes use of the kernel module API. Every module must export a \c ppp_module_info +structure. \n +KPPPInterface loads all specified modules and calls their \c ppp_module_info::add_to() +function. Depending on the type of module you should add the corresponding object +to the interface. + +\sa ppp_module_info + +*/ diff --git a/docs/user/ppp/PPPIntro.dox b/docs/user/ppp/PPPIntro.dox new file mode 100644 index 0000000000..0d95763e73 --- /dev/null +++ b/docs/user/ppp/PPPIntro.dox @@ -0,0 +1,18 @@ +/*! +\page ppp The PPP Kits + +The PPP stack is a kernel module that interfaces with the network stack. +Thanks to its modular nature new protocols and extensions can be added without +having to recompile the PPP stack. + + +- \ref kernelppp +- \ref userlandppp + +The kernel API is mostly intended for developers who want to write extension modules, +but you can also create and control PPP interfaces from within your own kernel modules. + +You should use the userland API for your applications because it exports helper +classes for accessing the kernel module from userland. Alternatively, you can talk +to the PPP interface manager directly through an \c ioctl() interface. +*/ diff --git a/docs/user/ppp/UserlandPPPIntro.dox b/docs/user/ppp/UserlandPPPIntro.dox new file mode 100644 index 0000000000..f2dcf2f426 --- /dev/null +++ b/docs/user/ppp/UserlandPPPIntro.dox @@ -0,0 +1,9 @@ +/*! +\page userlandppp The Userland PPP Kit (libppp.a) + +Classes: +- PPPInterface +- PPPInterfaceListener +- PPPManager + +*/