Использование стека lip  {#mainpage}
============

Основные особенности стека {#sect_features}
==============================================================
lip представляет собой TCP/IP стек для встраиваемых систем, разработанный фирмой [\"Л Кард\"](http://www.lcard.ru).
Основные особенности стека:
  - Ориентирован на использование без операционной системы.
  - Все функции стека неблокируемы, т.е. выполняют определенную работу и возвращают управление приложению, не ожидая внутри себя каких-либо событий. Это позволяет использовать его вместе с выполнением других задач без многопоточности. 
  - Не использует динамическое выделение памяти. Вся используемая память выделяется статически.
  - Требует небольшого количества RAM, что позволяет использовать в контроллерах без внешней памяти или располагать его полностью во внутренней памяти для повышения быстродействия. При этом возможности, требующие сколько-нибудь существенный объем RAM, имеют настройки, регулирующие использование памяти.
  - Реализация некоторых более высокоуровневых возможностей и более строгое следование требованиям RFC, чем в части минималистических стеках (таких как uIP), таких как полноценная передача потоков по TCP через псевдосокеты с основными алгоритмами, регулирующими передачу, дефргментация IP-пакетов и т.д.
  - Файл конфигурации позволяет оптимизировать ресурсы под требования проекта, включив в сборку только требуемые возможности.
  - Минимальное количество внешних зависимостей: стек требует только реализации таймера на основе системного счетчика и файл с макросами для используемого компилятора (см. ниже). В остальном стек использует только функции стандартной библиотеки (libc, newlibc или другой). Дополнительные зависимости может потребовать [порт](@ref lip_port) под конкретный контроллер.

Включение в проект {#sect_add_to_prj}
==============================================================
Для работы со стеком исходные коды стека должны быть включены в проект и собираться вместе с проектом. Стек не собирается в виде библиотеки, так как настраивается отдельно под каждый проект и кроме того некоторые модули могут использовать функции обратного вызова, которые должны быть реализованы в самом приложении.

Для подключения необходимо:
   - Скопировать исходные коды lip в отдельную директорию (например в поддиректорию проекта lib/lip). При использовании сборки через gnu make можно в makefile проекта включить файл lip/lip_src.mk (подробнее в комментариях в файле). При использовании других средств сборки, можно добавить все файлы исходных текстов в проект (если модуль не разрешен в конфигурации, то его исходники будут исключены препроцессором и их включение не приведет к дополнительному коду), но при этом включив исходники только одного [порта](@ref lip_port). При этом путь к lip.h должен быть включен в пути поиска заголовков.
   - Скопировать исходные коды таймера ltimer (например в поддиректорию проекта lib/ltimer) и включить файл lclock.c нужной реализации системного счетчика в сборку, а также пути к файлам ltimer.h и lclock_arch.h включить в пути поиска заголовков. 
   - Скопировать исходные коды специальных определений (inline, выравнивание, упаковка) для компилятора (lcspec) в отдельную директорию (например в поддиректорию проекта lib/lcspec), включить данную директорию, а также директорию для используемого компилятора, в пути поиска заголовков.
   - Создать [файл конфигурации](@ref lip_conf) lip_conf.h в одной из директории с заголовками проекта (вне lip, так как исходные коды lip должны оставаться одинаковыми и не зависеть от конкретного проекта) взяв за образец файл из директории lip/src/conf и изменив его в соответствии с требованиями проекта. Также [порт](@ref lip_port) под конкретный контроллер может иметь свой набор параметров, пример которых и описание находится в файле _lip_port_conf.h соответствующего [порта](@ref lip_port). Эти параметры можно определить как в lip_conf.h, так и в отдельно созданном в проекте файле lip_port_conf.h, который включить в lip_port.h, чтобы отделить я общие настройки и специфичные настройки порта.
   - Для вызова функций стека достаточно включить заголовочный файл lip.h, который автоматически включает все заголовки остальных разрешенных модулей. 

Стандартная последовательность вызовов {#sect_std_call_seq}
==============================================================

Стандартная последовательность вызовов выглядит следующем образом:
1. Первой функцией, которую необходимо вызвать до всех остальных функций стека является lip_init(), которая инициализирует все модули стека и начинает инициализацию аппаратуры (MAC-контроллера, микросхемы физического уровня).
2. Сразу после вызова lip_init() необходимо вызвать lip_eth_set_mac_addr(), чтобы установить MAC-адрес устройства. MAC-адрес как правило устанавливается на аппаратном уровне (для фильтрации входных пакетов) в процессе инициализации MAC-контроллера и стек не предоставляет возможности изменять его на лету. Для последующей смены MAC-адреса необходимо остановить работу стека и инициализировать его заново через lip_init().
3. Далее как правило следует установка IP-параметров. Стек предоставляет две основные опции:
  - Установить статические параметры, с помощью lip_ipv4_set_addr(), lip_ipv4_set_mask() и lip_ipv4_set_gate()
  - Получить IP-параметры автоматически используя @ref lip_dhcpc (с помощью lip_dhcpc_enable()) и/или @ref lip_ip_link_local (с помощью lip_ip_link_local_enable()). Оба механизма могут работать параллельно, при этом при обнаружении DHCP-сервера приоритет будет отдан адресу, полученному по DHCP, а в отсутствии его будет использоваться выбранный локальный (link local) адрес.
  
  Изменение адреса, разрешение или запрет протоколов для автоматического получения адресов возможен и на лету при работе стека.
4. Далее необходимо на протяжении всей работы со стеком периодически вызывать lip_pull() для выполнения фоновых задач (практически вся основная работа стека). Вначале выполняется продвижение процесса инициализации MAC-контроллера и микросхемы физического уровня до момента обнаружения установки связи на канальном уровне. Затем идет получение адресов на IP-уровне, если включен механизм автоматического получения IP-параметров. Узнать текущее состояние соединения можно с помощью lip_state().
5. Для завершения работы со стеком возможны два варианта:
  - Функция lip_close() приводит к немедленному останову работы стека с отключением всей проинициализированной аппаратуры. Однако данный вариант не позволяет корректно завершить работу остальных модулей (закрыть соединения, послать сообщения о завершении работы и т.п.).
  - Для корректного по возможности завершения работы необходимо вызвать lip_close_request(), передав в функцию время, которое дается для корректного завершения всех операций. Данная функция как и все остальные неблокируема и возвращает управления сразу. Далее необходимо для работы по останову всех модулей продолжать выполнять lip_pull() до тех пор, пока стек не перейдет в состояние #LIP_STATE_OFF.


Дальнейшая информация
===================================
Дальнейшая информация об использовании стека зависит от используемых модулей и содержится в описании соответствующего модуля, список которых можно посмотреть на соответствующей <a href="modules.html">странице</a>.

Как правило пользователя интересуют протоколы [транспортного уровня](@ref lip_lvl_transport) для передачи данных и реализации протоколов поверх одного из протоколов этого уровня, а также может использовать для своих целей реализованные протоколы [прикладного уровня](@ref lip_lvl_app).

 

  
  @defgroup  lip_conf Конфигурация стека
  @defgroup  lip_core Базовые функции

  @defgroup  lip_lvl_app       Прикладной уровень
    @defgroup lip_dns_sd DNS-SD
    @defgroup lip_mdns mDNS
    @defgroup lip_tftp TFTP
  @defgroup  lip_lvl_transport Транспортный уровень
    @defgroup  lip_udp UDP
    @defgroup  lip_tcp TCP
  @defgroup  lip_lvl_network        Сетевой уровень
    @defgroup  lip_ip IP
    @defgroup  lip_ipv4 IPv4
    @ingroup   lip_lvl_network
    @defgroup  lip_ipv6 IPv6
    @ingroup   lip_lvl_network
  @defgroup  lip_lvl_link      Канальный уровень и управление физическим устройством
  @defgroup  lip_misc Дополнительные модули


 

 
