Add preliminairy documentation for the SNMP agent.

doc/FILES

@@ -1,4 +1,5 @@
-savannah.txt  - How to obtain the current development source code.
-contrib.txt   - How to contribute to lwIP as a developer.
-rawapi.txt    - The documentation for the core API of lwIP.
-sys_arch.txt  - The documentation for a system abstraction layer of lwIP.
+savannah.txt   - How to obtain the current development source code.
+contrib.txt    - How to contribute to lwIP as a developer.
+rawapi.txt     - The documentation for the core API of lwIP.
+snmp_agent.txt - The documentation for the lwIP SNMP agent.
+sys_arch.txt   - The documentation for a system abstraction layer of lwIP.

doc/snmp_agent.txt

@@ -0,0 +1,86 @@
+SNMPv1 agent for lwIP [preliminairy]
+
+Author: Christiaan Simons
+
+This is a brief introduction how to use and configure the SNMP agent.
+Note the agent uses the raw-API UDP interface so you may also want to
+read rawapi.txt to gain a better understanding of the SNMP messages handling.
+
+Agent capabilities
+==================
+
+SNMPv1 per RFC1157
+  This is an old(er) standard but is still widely supported.
+  For SNMPv2c and v3 have a greater complexity and need many
+  more lines of code. IMHO this breaks the idea of "lightweight IP".
+  Note the S in SNMP stands for "Simple" and is actually a bad joke.
+
+MIB II per RFC1213
+  The standard lwIP stack management information base.
+  This is a required MIB, so this is always enabled.
+
+Loading additional MIBs
+  MIBs can only be added in compile-time, not in run-time.
+  There is no MIB compiler thus additional MIBs must be hand coded.
+
+Large SNMP message support
+  The packet decoding and encoding routines are designed
+  to use pbuf-chains. Larger payloads then the minimum
+  SNMP requirement of 484 octets are supported if the 
+  PBUF_POOL_SIZE and IP_REASS_BUFSIZE are set to match your
+  local requirement.
+
+Building the agent
+==================
+
+First of all you'll need to add the following define
+to your local lwipopts.h:
+
+#define LWIP_SNMP               1
+
+and add the source files in lwip/src/core/snmp
+and some snmp headers in lwip/src/include/lwip to your makefile.
+
+Note you'll might need to adapt you network driver to update
+the mib2 variables for your interface.
+
+Running the agent
+=================
+
+The following function calls must be made in your program to
+actually get the SNMP agent running.
+
+In the lwIP initialisation sequence call snmp_init() just after
+the call to udp_init().
+
+Exactly every 10 msec the SNMP uptime timestamp must be updated with
+snmp_inc_sysuptime(). You should call this from a timer interrupt
+or a timer signal handler depending on your runtime environment.
+
+Private MIBs
+============
+
+If want to extend the agent with your own private MIB you'll need to
+add the following define to your local lwipopts.h:
+
+#define SNMP_PRIVATE_MIB        1
+
+You must provide the private_mib.h and associated files yourself.
+Note we don't have a "MIB compiler" that generates C source from a MIB,
+so you're required to do some serious coding if you enable this!
+
+Note the lwIP enterprise ID (26381) is assigned to the lwIP project,
+ALL OBJECT IDENTIFIERS LIVING UNDER THIS ID ARE ASSIGNED BY THE lwIP
+MAINTAINERS!
+
+If you need to create your own private MIB you'll need
+to apply for your own enterprise ID with IANA: http://www.iana.org/numbers.html 
+You can supply it in your lwipopts.h #define SNMP_ENTERPRISE_ID your_id
+
+
+Agent internals [advanced use]
+==============================
+
+todo
+
+