summaryrefslogtreecommitdiffstats
path: root/docs/source/lib.md
diff options
context:
space:
mode:
authorLuca Muscariello <muscariello@ieee.org>2020-02-12 13:49:52 +0100
committerLuca Muscariello <muscariello@ieee.org>2020-02-12 17:51:13 +0100
commit56e29ea01914681f394e3a0af4169936079858a7 (patch)
tree2b364c9da3a44637e9e2ba87b7009424ad8b192b /docs/source/lib.md
parent202c6bc2788c943b15026c24900c321b9bbeed3c (diff)
[HICN-512] documentation bundle using sphinx
Change-Id: I1dcbca50f7406ef2714683547b6bb32463e1baf8 Signed-off-by: Luca Muscariello <muscariello@ieee.org>
Diffstat (limited to 'docs/source/lib.md')
-rw-r--r--docs/source/lib.md116
1 files changed, 116 insertions, 0 deletions
diff --git a/docs/source/lib.md b/docs/source/lib.md
new file mode 100644
index 000000000..58f23b510
--- /dev/null
+++ b/docs/source/lib.md
@@ -0,0 +1,116 @@
+
+The Hybrid ICN Core Library
+==============================
+
+## Introduction
+
+libhicn provides a support library coded in C designed to help developers embed
+Hybrid ICN (hICN) functionalities in their applications (eg. forwarder, socket
+API, etc.). Its purpose is to follow the hICN specification for which it
+provides a reference implementation, abstracting the user from all internal
+mechanisms, and offering an API independent of the packet format (eg. IPv4 or
+IPv6). The library is designed to be portable across both desktop and
+mobile platforms, and we currently aim at supporting Linux, Android, OSX and
+iOS, by writing the necessary adapters to realize hICN functionality in
+userspace according to the available APIs and permissions that each system
+offers.
+
+The library consists in several layers:
+- the core library (hicn.h) provides a standard hICN packet format, as well as
+an API allowing manipulation of packet headers;
+- an hICN helper, allowing an hICN stack to be built in userspace in a portable
+way, based on TUN devices and accessible though file descriptors;
+- a network layer allow the sending an receiving of hICN packets on those file
+descriptors, implementing both source and destination address translation as
+required by the hICN mechanisms;
+- finally, a "transport" API allows the forging of dummy interest and data
+packets.
+
+A commandline interface (hicnc) is also provided that uses the library and can
+for instance be used as a test traffic generator. This interface can be run as
+either a consumer, a producer, or a simple forwarder.
+
+## Folder content
+
+CMakeLists.txt CMkake global build file
+doc Package documentation
+README.md This file
+src
+ base.h Base definitions for hICN implementation
+ CMakeLists.txt CMake library build file
+ common.{h,c} Harmonization layer across supported platforms
+ compat.{h,c} Compatibility layer for former API
+ error.{h,c} Error management files
+ header.h hICN header definitions
+ hicn.h Master include file
+ mapme.{h,c} MAP-Me : anchorless producer mobility mechanisms
+ name.{h,c} hICN naming conventions and name processing + IP helpers
+ ops.{h,c} Protocol-independent hICN operations
+ protocol/* Protocol headers + protocol-dependent implementations
+ protocol.h Common file for protocols
+
+## Using libhicn
+
+### Platforms ###
+
+libhicn has been tested in:
+
+- Ubuntu 16.04 LTS (x86_64)
+- Ubuntu 18.04 LTS (x86_64)
+- Debian Stable/Testing
+- Red Hat Enterprise Linux 7
+- CentOS 7
+- Android 8
+- iOS 12
+- macOS 10.12
+- Windows 10
+
+Other platforms and architectures may work.
+
+### Dependencies
+
+Build dependencies:
+
+- c11 ( clang / gcc )
+- CMake 3.4
+
+Basic dependencies: None
+
+## Installation
+
+You can either use released packages, or compile libhicn from sources.
+
+### Release mode
+
+mkdir build
+cd build
+cmake ..
+make
+sudo make install
+
+### Debug mode
+
+mkdir debug
+cd debug
+cmake .. -DCMAKE_BUILD_TYPE=Debug
+make
+sudo make install
+
+## License
+
+This software is distributed under the following license:
+
+```
+Copyright (c) 2017-2019 Cisco and/or its affiliates.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at:
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```