/*! \mainpage Arch Rock IP/6LoWPAN Software Distribution (ASD)

\section intro_sect Introduction

This distribution provides kernel library APIs for developers to create 
applications using Arch Rock embedded IPv6/6LoWPAN technology.  
Wherever applicable, the interfaces are designed to be as close 
to the well-known Unix socket interfaces as possible.

The kernel library goes beyond 6LoWPAN and supports some 
common set of protocols above IPv6 as well as some
common embedded operating systems functionality that are 
useful for simplifying application development.

The kernel provides a single-thread event or callback driven 
concurrency model.  It does not support dynamic memory
allocation.  Please refer to \ref concurrency_model_sect
and \ref memory_sect sections for details.

The following shows the overview diagram of the kernel
library, which includes the following major API components.

- Kernel Services and interrupts: reboot and power management 
  control, or other kinds of network or processor notifications 
  via \em svcs.h, \em async.h, and \em platform.h.
- EEProm Management:  provide access to the internal/on-chip
  eeprom storage, which is shared with the kernel.  This is
  platform dependent and is supported via \em flash.h
- Timers and Time Services: provide interval timer abstractions,
  get time of day services if synchronized with Arch Rock 
  gateways via \em time.h.
- Ping6: ability to initiate ICMP ping request via \em icmp.h
- TCP/IPv6: supports Transmission Control Protocol (TCP) over
            IPv6 via \em socket.h.
- UDP/IPv6: supports User Datagram Protocol (UDP) over
            IPv6 via \em socket.h.
- Route Table Management: ability to set static routes and 
  access the routing table via \em route.h.
- Wireless 15.4 Radio Configuration: abstract the 15.4 radio
  with a familiar network interface card abstraction 
  via \em iwconfig.h.


\image html overview_diagram.png "Overview Diagram"
\image latex overview_diagram.pdf "Overview Diagram" width=6in

The kernel also supports a set of features not directly exposed
through the APIs.
- Power Management: the kernel automatically manages the
    power of the processor and the 15.4 radio.
- ICMPv6 Server: respond to different ICMPv6 requests.
- AR Network Management: network-level management services
    with Arch Rock gateways.
- Triply Redundant Meshing: self-configure IPv6 meshing
    over 6LoWPAN.
- Over-the-Air Software Update: this depends on the
   platform such as the existence of an external 
   flash to store programs.


For driver development, we try not to provide a hardware
abstraction layer for the on-chip I/O peripherals.  This gives 
developers maximum flexibility in configuring the I/Os for
their desire purposes.  They can either service the
corresponding interrupts that they have setup to 
interface with the sensors or busy wait inside a
callback handler from the kernel library.  

A driver is usually written in two parts.  One is
within the interrupt context, where fast actions 
are required to be serviced.  Heavy processing 
will continue in the application level context by
scheduling a callback through the scheduler, as
indicated in the diagram above.  See \ref interrupt_sect
for details.

\subpage design_overview_page 

\subpage function_overview_page

\subpage tutorial_page

*/

/*!
\page design_overview_page Interface Design Overview

\section api_cat_section API Types
This distribution does not support multi-threaded programming due to 
space constraints of the target platforms.  
Instead, asynchrony and concurrency are handled through callbacks.
All of the APIs in this offering fall into one of
the following categories.
- Function call with no callback.
- Function call with callback capability.
  This requires 3 additional arguments in the function signature:
  -# <em>a function pointer:</em> callback handler registration
         If NULL is passed, the next two arguments are ignored.  The
         call may fail return -1 or may succeed and return 0 without
         generating any notification.
  -# <em>a type specific pointer to hold callback arguments:</em> 
          instead of providing callback arguments via
          function signature, data structures
          are used to hold the callback arguments.  Caller
          allocates the structure, with the type defined by
          the particular function call, passes the pointer during
          the call, and the results will be stored in the
          structure upon the callback.  
          If NULL is passed, the call may fail and return -1
          or may succeed and return 0 for callback that takes
          no argument or callback that tolerates the caller
          to not take any callback arguments. Note that for the case of no
          argument callback, this automatically functions the
          same as a user context pointer described in the
          following next item.
  -# <em> a user context pointer:</em> this provides the convenience
          for users to maintain context along with continuation. 
          The kernel merely passes the pointer along the continuation
          callback.
- Callback handler.  All handlers from
  our APIs take the following function signature.
  \code void(*)(event_t event, void * cbargs, 
                void * context) \endcode
  @param event passed by the kernel to specify the type of event and
               potential error information using event_t.
  @param cbargs pointer to the return argument data structure passed to 
                   the kernel during call time
  @param context pointer to the user context passed to the kernel during
                call time
  \note \em event allows callback handler to inspect what
             function call the handler binds to originally.  This is done by
             using the function enumeration name defined in 
             #EventsEnum and check it against event.type.
	     Below is an example showing how a handler can
             tell the callback is originated from a timer
             function call.  The subtype field in event
             is defined by the function call itself.
        \code 
...
id = timer();
setitimer(id, &new_timeval, &old_timeval, 
          app_handler, NULL, NULL);
...

app_handler(event_t event, void * cbargs, void * context)
{
  if (event.type == SETITIMER)
    ....
}
\endcode
             
- Kernel and Interrupt Notifications.  All notifications take the same
  function signature as the callback handler.  
  A call must be made to bind a particular type of kernel or interrupt
  notification and to a function handler.  This binding
  may recur instead of being just a one-time notification.
  The binding is removed when an explicit call (e.g. stop or unbind)
  is made to not receive this particular kernel notification.

\section main_entry_sect Main() Entry Point

The first user code entry point from the kernel is a 
kernel notification with the name \em __main().  

\code void __main(event_t event, void * cbargs, void * context) \endcode

Since this shares the same signature as any
callback handler in our APIs, one can reuse this 
same handler over and over again to create 
a continuation loop.

\section error_handling_sect Error Handling

All function calls return 0 for success.
All function calls fail by returning -1 and 
setting \em errno appropriately except for
those that can be called within the interrupt
context.  These special calls are defined in \em async.h
and they return the appropriate \em errno
when error occurs. 

Callback handler may entail call-specific error 
information in data structure specified in \em cbargs.
Kernel notifications may entail error information
by setting <em>event.error</em> to <em>event.errno</em> 
appropriately.


\section concurrency_model_sect Concurrency Model
Our kernel library provides a single-threaded 
event driven concurrency model, with 
each event realized as a callback handler
scheduled by our kernel's scheduler.
The scheduler ensures that callback handlers 
are atomic with respect to each other.
That is, no callback can run until the 
current callback handler is completed.
\note This strictly requires that each callback handler
must run into completion, which means writing
a while(1) loop in the handler can hang the 
entire system.

However, interrupts can run and preempt any
callback handlers.  When interrupt handling
is completed, the interrupted callback handler resumes.
Race conditions can occur if any shared 
variables between the interrupt handler and
the callback handler is not handled properly.
One approach is to schedule a continuation 
callback handler in the interrupt handler
and access the shared variable when the
callback handler fires to maintain atomicity.
Another approach is to directly control 
atomicity using atomic APIs defined in
\em async.h.


\section interrupt_sect Interrupt Context
Our APIs cannot be called in the interrupt context except for
those that schedule a continuation in the kernel
context or those that control global interrupts for atomicity.

Our offering relies on timer and SPI interrupts to drive
the network stack and kernel services.  The design guideline
is to handle fast process in interrupt context and schedule
a continuation in the application context for more involved
processing.  This is exemplified by the following
diagram.

\image html concurrency_diagram.png "Overall Concurrency Diagram"
\image latex concurrency_diagram.pdf "Overall Concurrency Diagram" width=6in

A driver is usually written in two parts.  One is
within the interrupt context, where fast actions 
are required to be serviced.  Heavy processing 
will continue in the application level context by
scheduling a callback through the scheduler.

Busy waiting to handle I/O is possible within 
a callback handler as long as the busy waiting 
loop does not run "indefinitely".  Like any event-driven
systems, long busy waiting loop within a callback handler can 
take control of the system.  To avoid the situation, 
one can utilize a timer to poll for an I/O event 
periodically to avoid waiting for I/O within an infinite loop.

The kernel owns the SPI bus, the necessary I/O
pins, and interrupts to drive the 15.4 radio. It 
also uses a subset of hardware timers to support 
its time service.  The kernel may also use a subset 
of other interrupt vectors, which driver developers 
may need to get shared access.  This is a common case 
for some platforms in which the same interrupt
vector may be mapped to more than one kind of interrupt.
These interrupts are all listed in \em platform.h

For these interrupts, the kernel will
service interrupt handler if it is intended for the kernel.
Otherwise, the kernel will ignore it and notify the
application if there is an user interrupt handler
binds to this interrupt.  Refer to \em async.h to see
how to bind an interrupt handler with the kernel.
Note that once a user interrupt handler has called
the bind function to an interrupt shared with the kernel, it will
always get notified \em whenever the underlying
interrupt fires, even if the firing is intended 
for the kernel. This is to simplify the kernel for 
small footprint rather than administrating filtering
mechanism.  Therefore, it is recommended that 
user defined interrupt handlers that share interrupts with
the kernel should double check the interrupt flags 
to ensure the user is servicing the interrupt that
he or she desires.  

The list of interrupts used by or shared with 
the kernel is listed in \em platform.h.  For
other interrupts, user can connect to the
interrupt vector directly.


\section hal_sect Hardware Abstraction Layer
We do not offer any hardware abstraction layer
on the processor except the internal on-chip
non-volatile storage. Developers must create the
relevant code themselves to access the peripherals
and link it up to the kernel library.

\section rsrc_sect Resource Descriptor Model
Resources that have multiple instances would require 
a file descriptor access model.  These include socket,
timer, and scheduling for a continuation in application
context.  When the number of instances for each type
of resources has reached its limit, application must
close some opened ones for reuse.  Refer to 
RELEASE_NOTES to learn the limits.

\section memory_sect Memory Handling and Allocation
The kernel does not provide dynamic memory APIs.  
All memory should be statically allocated.

Memory ownership of \em cbargs in callback handlers is returned
back to the application upon the firing of the callback 
function. Kernel never owns the memory region pointed
by \em context.  It is purely intended for user context.

For callbacks that bind a resource descriptor with
a callback handler, \em cbargs is owned by the
kernel until the resource is closed explicitly
by a call.  Thus, application must copy contents
of the \em cbargs during each callback instance
if it desires to retain the information.

Similarly, calls that explicitly require
application buffers to operate require binding 
the buffer to a resource descriptor initially.  The
resulting buffer is released back to the application when
the resource is closed explicitly.  

\section proto_buf_sect UDP Fragmentation Buffer and TCP Queue Buffer
Our kennel library handles buffer queuing
for both UDP and TCP communications and buffers
are passed to the kernel through either \em udpbind
or \em tcpbind calls.

For UDP, the buffer used is purely for fragmentation
such that an application buffer is used
to support a single application data unit (message) that 
is larger than the supported maximum transfer
unit (MTU in net_device_info.device) in 15.4 radios.
The buffer is used for the underlying mechanism
to support link-layer fragmentation 
and reassembly.  If no fragmentation is used,
no buffer is required to pass down for UDP
communications.

For TCP, the goal is to use an application buffer
to queue up the byte streams for transmission
and reception. Applications may want to adjust the 
buffer size, depending on the amount of backlog it 
expects or observes with its intended 
bandwidth requirement.  Ideally, users should
choose a large enough buffer so that they
do not have to manage buffer back-pressure
themselves.  When back-pressure does occur,
users may need to do some additional buffering
of data above TCP and rely on \em notifywrite
from the kernel to notify the user that
more buffering is available for transmission.


\section power_sect Power Management
Power management of the radio and process
is handled automatically by the kernel library.  
Application can override the policy and keep the CPU from
sleeping.  Duty-cycling powering of the radio 
can also be controlled separately.  Application
can be notified before processor goes to sleep
each time if an handler is installed through kernel
services in \em svcs.h.

\section reboot_sect Watchdog and System Reboot
Application can reboot the system via a kernel
service call or it can get a notification that a reboot
is about to start when such reboot is administrated
by remote Arch Rock management tools.

Applications can get notification for each
watchdog event in the kernel to guard against
its own invariant.  The frequency of the
watchdog event is controlled by the kernel 
and is chosen to be 0.5 second.
So, application only gets notified for each
watchdog event.  If some invariants fail,
application needs to explicitly call
reboot through kernel services.

\section route_sect Route and Network Dynamics
Applications can get notifications on 
network dynamics such as route changes 
or that the node has joined or left a network.  
In addition, applications can add or remove
IPv6 static routes as well as examining the
entries in the routing table.  A host only option
is also available to disable a node from 
participating in routing traffic of others.

\section endianness_sect Network Address Endianness
APIs that have arguments with network address types,
such as defining the destination IP address or the
next hop address, expect big or network address
endianness.  If the endianness of the host is different,
applications need to convert endianness using the
provided APIs in \em inet.h.

\section sw_update_sect Remote Software Update
Depending on the platform, remote over-the-air software 
update can be supported in the future.
*/

/*!
\page function_overview_page Function overview

<b> ICMP </b>

\em ping() Perform the standard ICMP ping service to an unicast IP address or to a link local multicast address.

<b> IPV6 ROUTING </b>

\em num_rtentries() Get the number of valid route entries in the routing table.

\em routecntl() Get and configure the routing table. If successful, the routes in the route table can be extracted or changed.

<b> SOCKET PROGRAMMING </b>

\em socket() Create an endpoint for communication and return a descriptor 

\em send() Send a message on a socket in a connected state. 

\em sendto() Send a message on a socket in a connectionless state.

\em udpbind()  Give a UDP socket the local address, a user allocated buffer for message queuing, and a callback for reception notification.

\em tcpbind()  Give a TCP socket the local address, a user allocated buffer for message queuing, and a callback handler for interacting with the TCP stack.

\em connect()  Connect the socket referred to by the socket descriptor to an destination IP address. 

\em accept()  Accept an incoming connection on the socket referred to by the socket descriptor to an destination IP address.

\em inet_pton() Convert the character string src into a network address structure in the af address family, then copies the network address structure to dst.

\em inet_ntop() Convert a network address structure to the character string in the af address family.

<em> ntohs() htons() ntohl() htonl() </em> Convert byte order between network and host for short and long data types.

<b> CONTEXT SWITCHING </b>

\em continuation() Request a unique resource identifier that enables scheduling a continuation from the interrupt context to Arch Rock's application context. Note this call is safe to be invoked in the interrupt context.

\em sch_continuation() Schedule a continuation from the interrupt context to Arch Rock's application context. Note this call is safe to be invoked in the interrupt context.

\em continuation_close() Close a continuation resource identifier so that it may be reused.  close() is not used because this supports call within the interrupt context.

<b> INTERRUPT MANIPULATION/CRITICAL REGION PROTECTION </b>

\em atomic_begin() Disable global interrupt for the start of a critical section.

\em atomic_end() Enable global interrupt for the end of a critical section.

\em async_irqbind() Bind a callback handler to a particular interrupt vector that are partially used by or shared with the kernel.  

\em async_irqunbind() Unbind a previously installed callback handler to a particular interrupt vector that are partially used by or shared with the kernel.  

<b> TIME MANIPULATION </b>

\em gettimeofday() Access time of day.

\em settimeofday() Set time of day.

\em timer() Request a unique resource identifier.

\em gettitimer() Get value of an interval timer.

\em setitimer() Set the value of an interval timer.

<b> FLASH MANIPULATION </b>

\em flread() Read the on-chip flash

\em flsize() Get the total size of the internal non-volatile storage in bytes that are available for application to use.

\em flwrite() Write a buffer to the on-chip flash

<b> SYSTEM SERVICES </b>

\em close() Closes a resource identifier (e.g socket, timerid, or a resource id) so that it may be reused.

\em iwconfig() Configure the wireless link interface

\em notifywrite() Register a callback for when a socket identifier has enough buffer space to accept data for transmission.

\em svccntl() Invoke kernel services or listen for kernel notifications.
*/

/*!
\page tutorial_page ASD Tutorials

The tutorials are meant to demonstrate the ASD API by progressively more complex coding example, to get started, refer to
<b><A HREF="../../../../projects/doc/doc_main.html">projects/doc/doc_main.html</A></b>

*/
