This is a 2009/wk14 version of NoTA L_IN release 3.

Tested with Ubuntu releases 8.10.

L_IN

====

L_IN is lower level entity for NoTA DIP providing connection logistics and data transport layers for the stack.

It has a configuration file l_in_up.h in l_in_up directory.This file contains entities used by l_in_up viz 

l_in socket_count, timeout and also manages environment variables for Manager and Gateway.It can be configured

suitable to individual needs within the limits of NoTA.

Instructions for building L_IN

==============================

./configure

make clean all

The l_in library can be used with pkg-config or directly linking to the 

library files.

LManager

========

When running l_ins,  there needs to be LManager.  Information who is LManager

is given with environment variable NOTA_LMANAGER. This is important specially

when running with singleprocess H_IN stack.

example

-------

    NOTA_LMANAGER=1 ./your_application_sp your_application_params

    NOTA_LMANAGER=1 notaworld_svn/h_in/test/.libs/simple_tester_sn_sp

Transports

==========

Configure takes the selected Ldown as parameter. It can be changed by running

configure with parameter "--with-transports=" default value is tcp.

example

-------

    ./configure --with-transport=tcp

    ./configure --with-transport=fifo

Multiple reference L_IN_UPs

===========================

Multiple L_IN ups can be enabled within same process. This means that all the

calls to reference l_in_up's function l_in_get_instance() will create a new instance of the reference L_IN_UP. This enables running of multiple reference l_in_up within a single process. Further this meas that all l_in_up instances will load their l_downs separately, and so developer can run multiple instance of the same l_down within same process.

example

-------

To run the singleprocess memory l_down with multiple reference cores.

./configure --with-transports=single --enable-multi-reference-l_in_up

To run the l_in_up with TCP l_down with the possibility to have the l_downs within same process.

./configure --with-transports=tcp --enable-multi-reference-l_in_up

With refrerence h_core

----------------------

This one process feature can be further enlarged with enabling multiple h_cores within same process. All h_core instances will then load separate l_in_ups.

h_in> ./configure --enable-multi-reference-h_in_core

TCP l down (ld_tcp)

===================

TCP ldown by default  uses broadcast and multicast, but if developing in same

network, ther e is problems as two LManagers are existing. To avoid this also

ldown_tcp is provided with static ip support. With static ip, we always point

to LManagers  IP address. If two tcp_ldowns are  existing in same system, the

Lmanager one needs to be started first. LManager uses static port 7100.

To enable static ip one needs to have tcp transport enabled.

examples

--------

    ./configure --with-static_ip=127.0.0.1

    Above example also is a special case where NoTA network contains only loopback as the transport.

    ./configure --with-transports=tcp --with-static_ip=10.0.0.33

known problems

--------------

LManager always needs to be started first.

Occasianally tcp/ip server is left allocated, and Ldown isn't able to utilize

same tcp server port. This problems fixes it self usually within a minute, as

soon as the tcp server port 7100 is released by the system.

There is no environment variable  to change  the static address, or to change

the tcp server port. This feature is planned to be added there in future.

Instructions for using NOTA_TCP_IP_IF environment variable(wlan case especially)

===============================================================================

TCP now provides NOTA_TCP_IP_IF env variable, which allows the option of using 

default(eth) interface or wlan interface depending on the transport used for 

communication.This is done to fetch the broadcast address from the local iptables.

Default broadcast/multicast address in code doesn't work in case of wlan.If this

env variable is not provided then communication happens with the broadcast/multicast

provided in the code.It is advisable to have only one interface during communication.

Eg.

CASE 1: (without NOTA_TCP_IP_IF environment variable)

=======

Run SN as:

NOTA_LMANAGER=1 ./simple_tester_sn_sp

Run AN as:

./simple_tester_an_sp

CASE 2: (with NOTA_TCP_IP_IF environment variable and using ethernet interface)

=======

Run SN as:

NOTA_TCP_IP_IF=eth0 NOTA_LMANAGER=1 ./simple_tester_sn_sp

Run AN as:

NOTA_TCP_IP_IF=eth0 ./simple_tester_an_sp

CASE 3: (with NOTA_TCP_IP_IF environment variable and using wlan interface)

=======

Run SN as:

NOTA_TCP_IP_IF=wlan0 NOTA_LMANAGER=1 ./simple_tester_sn_sp

Run AN as:

NOTA_TCP_IP_IF=wlan0 ./simple_tester_an_sp

With daemon version there is no need to run with NOTA_TCP_IP_IF

Single process l_down (ld_single)

=================================

Single process l_down is designed to be run withing single process. It is 

able to provide l_down interface between multiple l_in_ups. Reasoning for

this l_down is that multiple h_in and l_in_up stacks can be run within same

process for testing and developing purpoces.

example

-------

To enable single process for l_in

./configure --with-transports=single

To enable multiple reference l_in_ups with single process ldown

./configure --with-transports=single --enable-multi-reference-l_in_up

And also enable multiple reference h_cores

h_in> ./configure --enable-multi-reference-h_in_core

USB l down (ld_usb)

===================

LdUSB provides USB adaptation for the NoTA devices. The code has been made and tested with Ubuntu/Linux laptop and N810. Laptop in host mode and N810 either in host or device mode. The mode is automatically checked, when ld_usb is started.

There are two versions of host side adaptation available: libusb v.0.1 and libusb v.1.0. (Libusb v1.0 is in file ld_usb_host_libusb_v1_0.c and must be manually taken into build).

Device side (N810) adaptation is made using gadgetfs.

Usage

-----

1. Connect laptop and N810 with a usb cable. 

2. Mount gadgetfs in N810 as root:

  # sudo gainroot 

  # insmod /mnt/initfs/lib/modules/2.6.21-omap1/gadgetfs.ko

  # mkdir /dev/gadget 

  # mount -t gadgetfs gadgetfs /dev/gadget          (try again when first try fails)

  # mount -t gadgetfs gadgetfs /dev/gadget

3. Start ld_usb (i.e. NoTA application) in N810 as root

4. Start ld_usb (i.e. NoTA application)in laptop as root

Known problems

--------------

The performance is poor. (This is due unreliable send in gadgetfs and resends. Better user-space interface is needed.)

Both N810 and laptop side must have sufficient permissions to access USB devices. At default, Linux gives only root users access to new devices. Easiest alternative is to execute code with root privileges. If this is unsuitable, additional configuration is needed (see e.g. www.gphoto.org/doc/manual/permissions-usb.html for example).

Libusb v1.0 does not support hotplugging. New NoTA usb devices are discovered only when ld_usb is started. If devices are connected later on they are not detected. Support for hotplugging has been promised for libusb v1.1.

Device-side initialization (gadgetfs configuration) fails if USB cable is not plugged and connected to USB host.

The solution does not configure automatically to every USB hardware/driver. 

- Maximum LdUSB packet size is 512 bytes. In slow USB connections (older than v2.0) this will cause problems. The packet size should be adapted dynamically.

- Some drivers in device-side (gadgetfs) may require different configuration

USB devices are recognized to be NoTA compatible using the following vendor and product ID's 0x0000, 0x0123. These are just for the laboratory tests. In real world they may cause clashes with other products.

Branch coverage

===============

Branch coverage is used to determine which parts of the code gets run. L_IN in default uses

'gcov' coverage package included in gcc compiler collection. "--enable-coverage" parameter

in ./configure scripts enables value "-g -O0 -ftest-coverage -fprofile-arcs -static" is set to

CFLAGS variable. This generates branching functionalities in compiled code as well as it enables

linking to gcov library, to enable runtime support of coverage features. To be able to do

branch coverage in libraries static linking needs to be enabled.

enabling and building

---------------------

Coverage is enabled with --enable-coverage flag to configure script. It is recommended

that possible old files are cleaned with command 'make clean_coverage'. Command 'make clean all'

cleans binary files and forces coverage support files to be generated.

   l_in$ ./configure --enable-coverage

   l_in$ make clean_coverage clean all

After the branch coverage configurations have been done, desired softwares can be run from where the

h_in branch coverage is aimed to study.

gcov results

------------

There is a script file to help getting results of coverage run. It requires a directory where to

store the results as a parameter. The rest of the parameters will be passed to the actual

gcov call as parameters.

   l_in$ ./coverage.sh gcov_result

or for more detail

   l_in$ ./coverage.sh gcov_result -b

lcov results (in HTML format)

-----------------------------

lcov_coverage.sh script file helps getting results of coverage run in HTML format. It requires a

directory where to store the results as a parameter.

   l_in$ ./lcov_coverage.sh lcov_result