doc: Adding documentations

LICENSE

@@ -1,20 +1,13 @@
-The MIT License (MIT)
-Copyright (c) 2016 Microsoft Inc
+Copyright 2016 Microsoft, Inc.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to
-deal in the Software without restriction, including without limitation the
-rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
-sell copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+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
 
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
+    http://www.apache.org/licenses/LICENSE-2.0
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
-THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+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.

MAINTAINERS

@@ -0,0 +1,7 @@
+# This file describes the maintainers for SwSS
+# See the SONiC project governance document for more information
+
+Name = "Shuotian Cheng"
+Email = "shuche@microsoft.com"
+Github = stcheng
+Mailinglist = sonicproject@googlegroups.com

README.md

@@ -1,14 +1,13 @@
-[![Build Status](https://sonic-jenkins.westus.cloudapp.azure.com/buildStatus/icon?job=swss-build)](https://sonic-jenkins.westus.cloudapp.azure.com/job/swss-build)
-# Switch State Service - swss
+[![Build Status](https://sonic-jenkins.westus.cloudapp.azure.com/job/sonic-swss-build/badge/icon)](https://sonic-jenkins.westus.cloudapp.azure.com/job/sonic-swss-build/)
 
-### This software repository must be treated as private and is only shared under NDA terms with Microsoft until publicly released.
+# Switch State Service - swss
 
 # Description
 The Switch State Service (SwSS) is a collection of software that provides a database interface for communication with and state representation of network applications and network switch hardware.
 
 # Contribution guide
 
-All contributors must sign a contribution license agreement before contributions can be accepted.  Contact kasubra@microsoft.com or daloher@microsoft.com.  Later this will be automated.
+See the [contributors guide](https://github.com/Azure/SONiC/blob/gh-pages/contributing.md) for information about how to contribute.
 
 ### GitHub Workflow
 

doc/swss-schema.md

@@ -0,0 +1,158 @@
+Schema data is defined in ABNF [RFC5234](https://tools.ietf.org/html/rfc5234) syntax.  
+
+###PORT_TABLE
+Stores information for physical switch ports managed by the switch chip.  device_names are defined in [port_config.ini](https://github.com/stcheng/swss/blob/mock/portsyncd/port_config.ini).  Ports to the CPU (ie: management port) and logical ports (loopback) are not declared in the PORT_TABLE.   See INTF_TABLE.
+
+    ;Defines layer 2 ports
+    ;In SONiC, Data is loaded from configuration file by portsyncd
+    ;Status: Mandatory
+    port_table_key      = PORT_TABLE:ifname    ; ifname must be unique across PORT,INTF,VLAN,LAG TABLES
+    device_name         = 1*64VCHAR     ; must be unique across PORT,INTF,VLAN,LAG TABLES and must map to PORT_TABLE.name
+    admin_status	    = BIT           ; is the port enabled (1) or disabled (0)
+    oper_status         = BIT           ; physical status up (1) or down (0) of the link attached to this port
+    lanes               = list of lanes ; (need format spec???)
+    ifname              = 1*64VCHAR     ; name of the port, must be unique 
+    mac                 = 12HEXDIG      ; 
+
+###INTF_TABLE
+intfsyncd manages this table.  In SONiC, CPU (management) and logical ports (vlan, loopback, LAG) are declared in /etc/network/interface and loaded into the INTF_TABLE.
+
+IP prefixes are formatted according to [RFC5954](https://tools.ietf.org/html/rfc5954) with a prefix length appended to the end
+
+    ;defines logical network interfaces, an attachment to a PORT and list of 0 or more 
+    ;ip prefixes
+    ;
+    ;Status: stable
+    key            = INTF_TABLE:ifname:IPprefix   ; an instance of this key will be repeated for each prefix
+    IPprefix       = IPv4prefix / IPv6prefix   ; an instance of this key/value pair will be repeated for each prefix
+    scope          = "global" / "local"        ; local is an interface visible on this localhost only 
+    if_mtu         = 1*4DIGIT                  ; MTU for the interface
+    family         = "IPv4" / "IPv6"           ; address family
+
+    IPv6prefix     =                             6( h16 ":" ) ls32
+                    /                       "::" 5( h16 ":" ) ls32
+                    / [               h16 ] "::" 4( h16 ":" ) ls32
+                    / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
+                    / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
+                    / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
+                    / [ *4( h16 ":" ) h16 ] "::"              ls32
+                    / [ *5( h16 ":" ) h16 ] "::"              h16
+                    / [ *6( h16 ":" ) h16 ] "::"
+
+     h16           = 1*4HEXDIG
+     ls32          = ( h16 ":" h16 ) / IPv4address
+
+     IPv4prefix    = dec-octet "." dec-octet "." dec-octet "." dec-octet “/” %d1-32  
+
+     dec-octet     = DIGIT                 ; 0-9
+                    / %x31-39 DIGIT         ; 10-99
+                    / "1" 2DIGIT            ; 100-199
+                    / "2" %x30-34 DIGIT     ; 200-249
+                    / "25" %x30-35          ; 250-255
+
+For example (reorder output)
+
+    127.0.0.1:6379> keys *
+    1) "INTF_TABLE:lo:127.0.0.1/8"
+    4) "INTF_TABLE:lo:::1"
+    5) "INTF_TABLE:eth0:fe80::5054:ff:fece:6275/64"
+    6) "INTF_TABLE:eth0:10.212.157.5/16"
+    7) "INTF_TABLE:eth0.10:99.99.98.0/24"
+    2) "INTF_TABLE:eth0.10:99.99.99.0/24"
+
+    127.0.0.1:6379> HGETALL "INTF_TABLE:eth0.10:99.99.99.0/24"
+    1) "scope"
+    2) "global"
+    3) "if_up"
+    4) "1"
+    5) "if_lower_up"
+    6) "1"
+    7) "if_mtu"
+    8) "1500"
+    127.0.0.1:6379> HGETALL "INTF_TABLE:eth0:fe80::5054:ff:fece:6275/64"
+    1) "scope"
+    2) "local"
+    3) "if_up"
+    4) "1"
+    5) "if_lower_up"
+    6) "1"
+    7) "if_mtu"
+    8) "65536"
+
+
+###VLAN_TABLE
+    ;Defines VLANs and the interfaces which are members of the vlan
+    ;Status: work in progress
+    key                 = DEVICE_NAME    ; must be unique across PORT,INTF,VLAN,LAG TABLES
+    vland_id            = DIGIT 0-4095
+    admin_status        = BIT ; administrative status for vlan up or down
+    attach_to           = PORT_TABLE.key
+
+###LAG_TABLE
+    ;a logical, link aggregation group interface (802.3ad) made of one or more ports
+    ;In SONiC, data is loaded by teamsyncd
+    ;Status: work in progress
+    key                 = LAG_TABLE:lagname    ; logical 802.3ad LAG interface
+    minimum_links       = 1*2DIGIT             ; to be implemented
+    admin_status        = "down" / "up"        ; Admin status
+    oper_status         = "down" / "up"        ; Oper status (physical + protocol state)
+    if_mtu              = 1*4DIGIT   ; MTU for this object
+    linkup
+    speed
+
+    key                 = LAG_TABLE:lagname:ifname  ; physical port member of LAG, fk to PORT_TABLE:ifname
+    oper_status         = "down" / "up"        ; Oper status (physical + 802.3ad state)
+    speed               = ; set by LAG application, must match PORT_TABLE.duplex
+    duplex              = ; set by LAG application, must match PORT_TABLE.duplex
+
+For example, in a libteam implemenation, teamsyncd listens to Linux `RTM_NEWLINK` and `RTM_DELLINK` messages and creates or delete entries at the `LAG_TABLE:<team0>`
+
+    127.0.0.1:6379> HGETALL "LAG_TABLE:team0"
+    1) "admin_status"
+    2) "down"
+    3) "oper_status"
+    4) "down"
+    5) "mtu"
+    6) "1500"
+
+In addition for each team device, the teamsyncd listens to team events
+and reflects the LAG ports into the redis under: `LAG_TABLE:<team0>:port`
+
+    127.0.0.1:6379> HGETALL "LAG_TABLE:team0:veth0"
+    1) "linkup"
+    2) "down"
+    3) "speed"
+    4) "0Mbit"
+    5) "duplex"
+    6) "half"
+
+
+###ROUTE_TABLE
+    ;Stores a list of routes
+    ;Status: Mandatory
+    key           = ROUTE_TABLE:prefix
+    nexthop       = *prefix, ;IP addresses separated “,” (empty indicates no gateway)
+    intf          = ifindex? PORT_TABLE.key  ; zero or more separated by “,” (zero indicates no interface)
+    blackhole     = BIT ; Set to 1 if this route is a blackhole (or null0)
+
+
+###NEIGH_TABLE
+    ; Stores the neighbors or next hop IP address and output port or 
+    ; interface for routes
+    ; Note: neighbor_sync process will resolve mac addr for neighbors 
+    ; using libnl to get neighbor table
+    ;Status: Mandatory
+    key           = prefix PORT_TABLE.name / VLAN_INTF_TABLE.name / LAG_INTF_TABLE.name = macaddress ; (may be empty)
+    neigh         = 12HEXDIG         ;  mac address of the neighbor 
+    family        = "IPv4" / "IPv6"  ; address family
+
+
+###Configuration files
+What configuration files should we have?  Do apps, orch agent each need separate files?  
+
+[port_config.ini](https://github.com/stcheng/swss/blob/mock/portsyncd/port_config.ini) - defines physical port information  
+
+portsyncd reads from port_config.ini and updates PORT_TABLE in APP_DB
+
+All other apps (intfsyncd) read from PORT_TABLE in APP_DB
+