Fábio Coutada
ae6144a1c5
- Extract 37 of 45 PDFs under docs/ to docs-extracted/ - Preserve directory structure (apex, cdk, development, platform, etc.) - Add docs-extracted/index.md with navigation table - 8 PDFs were 0-byte/empty and could not be extracted
146 KiB
| title | source | category | pages | extracted |
|---|---|---|---|---|
| Anis Reference Manual | docs/development/anis-reference-manual.pdf | development | 72 | 2026-07-06T23:05:34.034899 |
Anis Reference Manual
Extracted from
docs/development/anis-reference-manual.pdf(72 pages). Figures, diagrams, and tables may not render accurately in plain text.
ANIS
A Certifiable UDP/IP Stack for PikeOS
Am Pfaffenstein 14, D-55270 Klein-Winternheim
Notice: The contents of this document are proprietary to
SYSGO GmbH and shall not be disclosed, disseminated,
copied, or used except for purposes expressly
authorized in writing by SYSGO GmbH.
ANIS for PikeOS PikeOS D5.0, Document Version
c 2005 – 2019 SYSGO GmbH
SYSGO GmbH Email: office@sysgo.com Am Pfaffenstein 14 55270 Klein-Winternheim, Germany http://www.sysgo.com
All rights reserved. PikeOS is a trademark of SYSGO GmbH. The designations used to identify other software or hardware products in this publication may be trademarks of their manufacturers or sellers. Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.3 Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2 ANIS File Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.1 Adding ANIS to an Integration Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2 ANIS File Provider Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2.1 Main Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2.2 Partition Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.3 ARP Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.4 Network Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.2.5 ARP Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.3 VMIT Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.4 ANIS Configuration on File Provider Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.5 ANIS File Provider Memory Needs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.6 ANIS Features, Constraints and Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.6.1 MTU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 2.6.2 Instrumentation Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.6.3 Internal Buffers Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.6.4 Unbound Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.6.5 Reserved Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.6.6 Localhost Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.6.7 Multicast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.6.8 Broadcast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.9 Multi Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.10 Dynamic ARP without ARP queueing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 2.6.11 ARP packet validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 3 PikeOS Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.1 Configuring your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.2 Initializing and Using ANIS in your Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 3.3 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.4 Sample Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 4 ANIS PikeOS API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.1 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2 AnisSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2.1.1 struct in_addr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2.1.2 struct sockaddr_in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2.1.3 struct sockaddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2.1.4 struct ip_mreq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 4.2.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.2.4 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 4.2.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.2.5.1 anis_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4.2.5.2 socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.2.5.3 bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 4.2.5.4 recvfrom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
4 CONTENTS
4.2.5.5 sendto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.2.5.6 getsockname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.2.5.7 getsockopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.2.5.8 setsockopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.2.5.9 socket_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.3 AnisInstr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.3.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.3.1.1 struct anis_instr_intf_stat_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4.3.1.2 struct anis_instr_stat_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.3.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 4.3.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.3.4 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 4.3.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 4.3.5.1 anis_instr_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 4.3.5.2 anis_instr_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.3.5.3 anis_instr_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 5 POSIX Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 5.1 Configuring your Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 5.2 Configuring Project Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 5.3 Initializing and Using ANIS in your Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 5.4 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5.5 Sample Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5.5.1 Unicast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5.5.2 Multicast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 6 ANIS POSIX API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 6.1 Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 6.2 AnisSocket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 6.2.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 6.2.1.1 struct fd_set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 6.2.1.2 struct in_addr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 6.2.1.3 struct sockaddr_in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 6.2.1.4 struct sockaddr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 6.2.1.5 struct ip_mreq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 6.2.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 6.2.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 6.2.4 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 6.2.4.1 anis_init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 6.2.4.2 socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 6.2.4.3 bind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 6.2.4.4 getsockopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 6.2.4.5 setsockopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 6.2.4.6 getsockname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 6.2.4.7 recvfrom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 6.2.4.8 sendto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 6.2.4.9 select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 6.3 AnisInstr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 6.3.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 6.3.1.1 struct anis_instr_intf_stat_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 6.3.1.2 struct anis_instr_stat_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 6.3.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 6.3.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 6.3.4 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 6.3.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 6.3.5.1 anis_instr_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
CONTENTS 5
6.3.5.2 anis_instr_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.3.5.3 anis_instr_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
7 ANIS Startup Configuration API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 7.1 Configuration Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 7.2 AnisStartupConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 7.2.1 Structure Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 7.2.1.1 struct anis_config_header_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 7.2.1.2 union anis_config_value_u . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 7.2.1.3 struct anis_config_property_s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 7.2.2 Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 7.2.3 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
1 Introduction
1.1 Purpose
ANIS is a UDP/IP networking stack compatible with the standard RFC specifications. It is implemented as a PikeOS file provider with POSIX and PikeOS APIs. A standard socket interface is available to applications running under PikeOS, written using the POSIX or PikeOS (native) personalities. Following features are supported by the ANIS:
• UDP sockets: The ANIS standard socket API allows applications to exchange messages with other hosts on the
network using the UDP protocol.
• IPv4: Internet Protocol version 4 as Transport Layer.
• ARP: Static ARP table or Dynamic ARP resolution. Answering ARP Request messages for the MAC address of the
networking component with an ARP Reply message. Issuing ARP request messages and processing replies in case
of Dynamic ARP table.
• ICMP: Responds to ping requests from known hosts on the network.
• Unicast: Point to point communication.
• Multicast: Group organized communication.
• Broadcast: Communication to address all recipients simultaneously.
• IGMPv2: Reports groups membership and answers membership queries.
• Localhost: Localhost loopback virtual device.
• Multi interface: Up to 7 network interfaces can be configured.
• Multi client: Up to 8 client applications using the ANIS stack in parallel.
• Instrumentation: Instrumentation API for both PikeOS and POSIX personalities.
1.2 Configuration
The PikeOS Project Configurator is used to configure the ANIS file provider. All ANIS networking parameters are statically configured. This document gives a short overview on how to integrate the ANIS network stack as a file provider into a PikeOS project. More instances of ANIS can be included and up to 8 applications can use one instance of ANIS file provider at time. ANIS must be used in conjunction with a network driver file provider. Currently, any standard PikeOS Ethernet driver is supported.
1.3 Files
The ANIS API header files and libraries for the POSIX personality are located in the POSIX installation path for the target architecture, /opt/pikeos-D5.0/target///posix/anisfp. The ANIS API header files for the PikeOS personality are located in the installation path for the target architecture, /opt/pikeos-D5.0/target///include/anisfp.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Files 7
In the paths mentioned above, stands for the name of the relevant architecture, for instance x86, and stands for the relevant processor, for instance amd64.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
2 ANIS File Provider
2.1 Adding ANIS to an Integration Project
In the Project Configurator, ANIS is defined as a new application type. This allows a name to be specified for each ANIS instance in the project and to assign each ANIS instance to a given PikeOS partition. As a consequence, more than one instance of ANIS can be included in your project as long as each instance has a different name and is in a separate partition. Each ANIS instance will then be a file provider available through the path anisName: where „anisName“ is the actual name given to the ANIS instance.
2.2 ANIS File Provider Configuration
When ANIS is added to a project, a list of parameters becomes available in the Project Configurator. The parameters are described below. Default values are shown in brackets.
2.2.1 Main Configuration
• Name [anisfp]: Name of the ANIS instance. This is the name given in the configuration of a POSIX application
wishing to use this instance of ANIS.
• Sockets [500]: This setting defines the number of sockets that can be opened by an application. For POSIX
applications, keep in mind that at most 512 POSIX file descriptors are available, and that ANIS will consume one
file descriptor for its internal control thread. So, at most 511 sockets would be available (each socket consumes one
file descriptor), assuming the application opens no other files. For PikeOS applications, the upper limit of the API is
512 sockets (the file provider itself has no upper limit). Each of these limits are applicable per client.
Note that the number of sockets possible to open is also limited by the number of file descriptors assigned to a partition.
The MaxFDCount parameter shall be adapted in all ANIS and client application partitions.
• Buffers [256]: This defines the number of network buffers that ANIS will allocate at startup. Network buffers are
used to store incoming and outgoing data packets in ANIS. The size of each network buffer is dependent on the MTU.
Setting this parameter to a low value will probably cause received messages to be lost if the application does not read
them fast enough. Setting it to a higher value increases the memory footprint of the ANIS stack. The network buffers
pool is shared by all configured interfaces, so adding more interfaces requires adaptation of the amount of buffers
accordingly. For more details please refer to chapter 2.6.3.
• MTU [1500]: Maximum Transfer Unit. This setting is directly dependent on the physical network being used. It defines
the maximum size of a packet emitted by the network interface. This should usually be set to the standard of your
network unless there are special needs (for example, vlan needs to be able to encapsulate one packet emitted by
ANIS in another one to crypt it). There exist two more limitations. If the standard PikeOS product Ethernet driver is
used, MTU of 1500 is the only supported and allowed value. If other driver is used ANIS supports MTU between 68
bytes to 8178 bytes. If the MTU is set outside of this range, health monitoring event is issued during start of the ANIS.
• Peercache [10]: This sets the maximum number of entries in the peer cache. In the IP protocol, each packet coming
from a specific source has a unique ID to enable detection of duplicate packets and to allow fragmentation/reassembly.
ANIS stores a cache of the last packet ID that has been emitted to a given destination or that has been received from
a given host.
Setting this to a low value will have two effects. It will force ANIS to overwrite old entries and transmit packets with
ID 0, which will force resetting the counter of the destination and disable duplicate detection. It will also make ANIS
unable to detect duplicate incoming packages.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
ANIS File Provider Configuration 9
• Number of interfaces [1]: Number of Ethernet interfaces to be used by the ANIS instance. Configuring more interfaces than actually needed may have impact on ANIS performance. Minimal number of the buffers to be configured is number of interfaces configured in the system + 1. Reception threads per interface allocates one buffer at startup and at least one buffer is needed for the sending.
• Enable Startup Configuration [false]: If this option is enabled, the ANIS file provider reads an additional configura- tion file on startup, see section 2.4.
• Startup Configuration File Path [shm:anis.config]: This option specifies the path to the configuration file. Read access rights to the file are enabled automatically. If the file resides on a volume, the system integrator should add a volume partition access component (PIKEOS_POOL/volume-provider/volume-partition-access.cmp) to enable mount access rights in the ANISFP partition.
• Transmit errors are fatal [false]: This option causes the ANIS File Provider to raise a PikeOS Health Monitor Error if the underlying ethernet driver reports any error in a write operation. This option should be disabled if the ethernet driver does not support blocking write operations with infinite timeout.
• Enable diagnostic messages [none]: This option enables diagnostic and debugging messages at run time. The messages are printed by the ANIS File Provider to the PikeOS console. The value „info“ enables diagnostic messages at startup, the value „debug“ enables all diagnostic and debugging messages.
• Binary Origin [HOST]: This setting defines the location of the ANIS file provider process image. With the default value HOST, the ANIS file provider process image is copied from the host file system to an automatically chosen location in the PikeOS ROM file system. Alternatively, it can be loaded from shared memory file system (SHM) or arbitrary location in the PikeOS ROM file system (RFS). Depending on the binary origin, the host path (parameter HOST_PATH), name of the shared memory (SHMNAME) and PikeOS file system path (PIKFILE) can be specified.
2.2.2 Partition Configuration
If you select the option „Enable partition configuration“ the following attributes of the ANIS resource partition can be modified in the Project Configurator.
• Maximum priority [60]: Maximum priority of the process. The priority must be greater than or equal to 4.
• Maximum thread count [511]: Maximum number of threads.
• KMEM size [0x90000]: Size of the kernel memory.
• RAM size [0x400000]: Size of the „MBUF_anisName“ MemoryRequirement. For information on how to chose its size refer to section 2.5.
2.2.3 ARP Configuration
• ARP configuration [dynamic]: This parameter can be set to „static“ to have a completely static network config- uration. When this is set to „dynamic“, ARP requests are generated and answered to find out the MAC addresses corresponding to the IP addresses. If dynamic ARP table configuration is selected, static table records are completely ignored, even if they are in the configuration.
• ARP table size [60]: Size of the internal dynamic ARP cache table, where minimal size is 10 records and maximal size is 250 records. Static ARP table is limited to 60 records. The cache table is shared amongst all interfaces. Note that the size of the ARP table is recommended to be greater than the number of local network devices where the data are sent simultaneously by ANIS. Otherwise, ANIS may exhibit packet loss because it is not able to perform ARP translation.
• ARP resolution timeout [1000]: Timeout in milliseconds until the next ARP resolution packet is allowed to be sent for the same IP. Valid range is from 0 to 100000 [ms].
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
10 ANIS File Provider
• ARP queue length limit [1]: Maximal length of ARP queues. The value 0 disables ARP queueing.
A queue of packets with unresolved destination address is associated with each unresolved ARP table entry. If the
maximal length is reached, the oldest packet is dropped from the queue.
The length limit times the ARP table size must be smaller than the half of the configured number of network buffers.
• Enable the SO_FLUSH_ARP socket option [false]: This parameter enables the ANIS-specific socket option
SO_FLUSH_ARP. This socket option allows any client to flush the ARP table. See also the documentation of
setsockopt().
2.2.4 Network Interfaces
ANIS can be connected to up to 7 Ethernet network interfaces and to one virtual localhost loopback interface. Only the physical interfaces need to be configured by following parameters:
• Interface ID [0]: Interface ID. Must be unique across interfaces.
• IP [192.168.0.2]: The IP address of the interface on the network.
• NetMask [255.255.255.0]: The network mask of the interface.
• TLL [255]: The Time To Live value of packets emitted by the interface. This will determine how many times a packet
can be transferred from one network to another by routers.
• Gateway [0.0.0.0]: Without static configuration, this parameter allows you to define a default gateway to communicate
with network hosts which are not on the same network. In static mode, this can be done by setting the MAC address
of the gateway for hosts which are not on the local network.
• Multicast support [Level 1]: This parameter can be set to „Level 2“ to have full support for multicast. Keeping this
set to „Level 1“ means only sending of multicast datagrams is supported, their reception is disabled.
2.2.5 ARP Table
When static configuration is selected, a static ARP table is used to find the MAC address corresponding to an IP address when sending packets. Each table entry defines the MAC address for a given IP address. Each entry has the following parameters:
• IP [0.0.0.0]: IP address of the destination host.
• MAC [0x00,0x00,0x00,0x00,0x00,0x00]: MAC address of the destination.
In the non static configuration the size of the ARP table can be changed using the configuration entry ARP table size. The default size is 60 entries.
2.3 VMIT Configuration
When ANIS has been added to a project using the Project Configurator, two parameters must be set in the VMIT, depending on the configuration.
• In the POSIX or PikeOS application partition, file access rights must be granted to use the ANIS file provider. A
new FileAccess entry must be added to the partition’s FileAccessList to grant access to the ANIS instance the
application wishes to use. If the ANIS file provider instance is named „anisfp“, then the FileAccess entry must
provide Read/Write rights to the FileName anisfp:*.
• In the partition containing the ANIS file provider, the size of the MemoryRequirement named „MBUF_anisName“ (by
default „MBUF_anisfp“, see 2.2.1) should be adjusted to fit the configuration. The next section explains in detail how
the size of this entry can be computed based on the configuration parameters.
This parameter can be also modified using the Project Configurator as described in 2.2.2.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
ANIS Configuration on File Provider Startup 11
2.4 ANIS Configuration on File Provider Startup
On startup, ANIS file provider may load additional configuration from a file in the PikeOS File System. Path to the config- uration file is specified in the property filesystem in prop:/anis///startupConfig, where and are the partition and process name of ANIS file provider. The configuration file may override any ANIS configuration property. If the configuration file does not exist or is empty, the static configuration is used without modification. The configuration file format is described in the header file anisStartupCon- fig.h, see section 7.2. The ANIS file provider indicates success of the configration phase by setting the operating mode of its partition to VM_PART_MODE_NORMAL. The ANIS file provider should run in a dedicated partition if startup configuration is used.
2.5 ANIS File Provider Memory Needs
The „MBUF_anisName“ MemoryRequirement must be adapted to fit the ANIS configuration. Memory for ANIS internal data structures is allocated from this MemoryRequirement during the file provider initialization phase (there is no allocation during runtime). The size needed for this MemoryRequirement can be divided into 8 parts:
• 192 kB + ThreadsStacks for internal needs and stacks of the created threads. Stack allocation for the threads
depends on the configured number of interfaces. It can be calculated as follows: (((2 * Number of interfaces) + 3) *
16kB)
• Sockets * 256 bytes for open socket data.
• Peercache * 32 bytes for the peer cache.
• (MTU + 48) * Buffers bytes for the network buffers.
• max(Sockets, Buffers) * 64 bytes for the socket lists.
• Interfaces * Sockets * 640 bytes for ethernet multicast group tracking.
• (ARP table size) * 56 bytes for ARP table.
• Size of the startup configuration file in bytes for startup configuration loading.
The numbers are valid for 64-bit platforms. Using these formulas and the configuration values, provide the required size of the „MBUF_anisName“ MemoryRequirement.
Note: The size must be rounded up to next multiple of the PikeOS page size (4096 bytes).
2.6 ANIS Features, Constraints and Hints
The following subchapters describe ANIS features and constraints the user shall take into account.
2.6.1 MTU
The MTU can be configured only as system wide parameter. This configured MTU is also used by the localhost loopback. If the MTU is too small and large packets are passed through the localhost loopback device, the fragmentation and reassembly can have performance impact. Since fragmentation is supported also for the Multicast and Broadcast messages, this could also lead to some performance penalty.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
12 ANIS File Provider
2.6.2 Instrumentation Counters
Instrumentation counters represent a sum of errors of a given class for each of the configured interfaces separately, including localhost loopback. More details can be found in the chapter 6.3.
2.6.3 Internal Buffers Management
In ANIS there is one pool of internal buffers configured via the option „Buffers“ 2.2.1. It is used for sending and reception and it is shared by all of the configured interfaces including the localhost loopback. The application developer shall carefully set the maximal usage of receive buffers per socket via SO_RCVBUF setsockopt() to not influence other communication channels. If the receive buffer limit is reached messages are dropped without notification. In case IP_MULTICAST_LOOP is enabled (which is the default) the reception buffers are used to create a copy of any multicast message to be sent. That copy is sent back to the source socket. If the copy creation does not succeed due to the reception buffer limit the message is not looped back, it is only sent on wire. In case the localhost loopback interface is the target interface, the reception buffers are used to create a copy of the message in order to send it. If the copy creation does not succeed the message is dropped without any notice. In case of outcoming broadcast traffic all messages are received back by all the sockets bound to the message target port and the same subnet segment. The reception buffers are used to create a copy of the messages to be delivered back to the target sockets. If the copy creation does not succeed for a given socket the message is dropped on that socket without any notice. Delivering to further sockets and wire continues. The whole amount of the configured internal buffers shall not be fully distributed to the sockets for the reception. There is also socketless IGMP traffic to be handled, thus some buffers shall remain unassigned to handle it. For the calculation of the needed reception buffer size it is essential to know that internal buffers do not hold only the payload of a UDP message. They contain also some ancillary data for better performance of the data passing from Ethernet driver to the ANIS stack. Following data are stored within the internal buffers together with the payload: MAC_header(14 bytes), UDP_header(8), IP_header(20 bytes) * num_of_fragments + UDP_payload. This means the whole received packets are stored in the reception internal buffers including all the protocols headers. Some rules need to be followed to have internal buffers under full control:
• Whenever a socket is created, apply the limit using SO_RCVBUF setsockoption.
• There need to be 6 spare buffers left for IGMP packets.
• For sending regular UDP messages there need to be enough spare buffers to fit all the fragments of the message
being sent. In the worst case this is (65536 / MTU) rounded up.
• Buffers limit applies also to the localhost loopback, multicast loop enabled sockets and broadcast self-looped traffic.
• Even if the socket is reserved for sending only, buffers shall be limited as well. There still can be incoming traffic, since
the socket is bound, especially in multicast and broadcast environments. In this case it is recommended to set the
amount of receive buffers to zero.
Note: These rules assume following system configuration: The ANIS file provider has lower priority than the used Ethernet driver and higher priority than any of the connected client applications. Also the ANIS file provider is in the same time partition as the used Ethernet driver. If these conditions are not met the buffer management may change completely. For example, if a client application has higher priority, it might exhaust all buffers by repeated transmission.
2.6.4 Unbound Sockets
Data transfers on unbound sockets are not supported by ANIS. Therefore, all the data tranfering sockets need to be bound to a local interface IP or INADDR_ANY address, which covers all interfaces including local loopback.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
ANIS Features, Constraints and Hints 13
2.6.5 Reserved Ports
The UDP port 0 is reserved and should not be used. Nevertheless, ANIS supports binding sockets and sending packets to any port. Unlike Linux and other *nix systems, zero port number does not have any special meaning in ANIS APIs.
2.6.6 Localhost Interface
Here is a list of supported features for the localhost loopback interface:
• Unicast traffic only: No other types of traffic except IPv4/UDP is supported. If the application needs to use other
protocols it needs to implement them itself.
• One instance only: Localhost loopback interface is not shareable between ANIS instances.
• Address range: Whole address range 127...* is supported. Or any of the local IP address of the system configured
Ethernet interfaces.
• Netmask: Netmask is hardcoded to be 255.0.0.0.
• Bind to INADDR_ANY: Socket bound to the INADDR_ANY address also incorporates localhost virtual device.
• MTU: MTU is the same as configured for the whole system. For more details please refer to 2.2.1 and 2.6.1 chapters.
• TTL: TTL set to 1.
• Limit of receive buffers: SO_RCVBUF option for setsocket call is supported. For more details please refer to the
chapter 2.6.3.
2.6.7 Multicast
Fragmentation is supported for Multicast. Binding to multicast addresses is not supported. A socket needs to be bound to the local IP or INADDR_ANY, and then used for the multicast communication. For the reception of the multicast traffic setsockopt(IP_ADD_MEMBERSHIP) needs to be called on the given socket with the group the socket could get a member of. Up to 20 groups per socket are supported. For the sending of the multicast traffic setsockopt(IP_ADD_MEMBERSHIP) is not needed to be called on that socket. There are some specific details related to the IP_MULTICAST_LOOP and IP_ADD_MEMBERSHIP. For more information refer to the 6.2.4.5. Also note that full multicast support is by default disabled for each interface (see 2.2.4). Message sending scheme:
• Socket bound to local IP: Multicast message is always sent through bound interface.
• Socket bound to INADDR_ANY: Multicast message is sent out on the interface the setsocktopt(IP_ADD_MEMBER-
SHIP, LOCAL_IP) was called for. If the outgoing interface was specified using the setsockopt(IP_MULTICAST_IF)
call, the specified interface is used all the time as outgoing interface, regardless of the further calls to the setsock-
topt(IP_ADD_MEMBERSHIP, LOCAL_IP) on the same socket.
In case of usage of IGMP snooping in the network, it is crucial to guarantee proper functionality of the used network devices. ANIS implements IGMPv2 host only functionality, thus either IGMP querier, static multicast routing or dummy forwarding of all the multicast traffic has to be used. If this functionality is not properly setup communication over multicast might not be possible or it will stall after some time, because the multicast routing tables will be dropped by the network routing devices.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
14 ANIS File Provider
2.6.8 Broadcast
Unlike Linux and other *nix systems, ANIS does not support SO_BROADCAST setsockopt option to enable broadcast messages on the given socket. List of features:
• Broadcast traffic is enabled by default on all the created sockets.
• Fragmentation is supported for the broadcast messages.
• Only direct-segment broadcast messages are supported, thus reception of the 255.255.255.255 is not supported.
• No broadcast messages are delivered to sockets bound to the localhost loopback.
Message sending scheme:
• Socket bound to local IP: Check if the target IP is in the same subnet segment as local IP, or target IP is
255.255.255.255. If target IP is 255.255.255.255 it is modified to the direct-segment address before sending.
• Socket bound to INADDR_ANY: Message will be sent by the first Ethernet interface found based on the subnet
netmask. If the target IP is 255.255.255.255 first configured Ethernet device will be used and the IP will be modified
to the direct-segment address before sending.
2.6.9 Multi Clients
Up to 8 client applications are supported to communicate using ANIS in parallel. To setup a system properly in a usable and robust way it is crucial to use Time Partitioning technology provided by PikeOS. Otherwise the scheduling is based on the priority of the threads and client applications and may lead into a situation with unbalanced data throughput. For more basics about PikeOS scheduling and Time Partitioning refer to /opt/pikeos- D5.0/documentation/pikeos-user-manual.pdf It is important to understand that rescheduling the CURRENT thread due to a BLOCK or STOP event does guarantee that the thread is placed to the end of the ready queue. Rescheduling the CURRENT thread due to higher priority thread scheduling puts the CURRENT thread to the beginning of the ready queue. And since the Ethernet threads and ANIS core threads have higher priority they are scheduled each time a packet is sent, and the CURRENT sending thread is placed to the beginning. The CURRENT thread is then scheduled immediately when the ready queue with its priority is chosen again. Thus it can generate the traffic again and keep occupying the CPU and network bandwidth. With the Time Partitioning in place the CURRENT thread is scheduled only until the configured time is spent, and then the next one is taken.
2.6.10 Dynamic ARP without ARP queueing
When ARP queueing is disabled, ANIS immediately discards outgoing IP packets if the MAC address of the destination (or the default gateway) is not known. This behavior is the same in both static and dynamic ARP configuration. The first UDP packet sent by an application to a remote host is usually discarded. When an application tries to send the packet, the MAC address of the destination is not known. ANIS discards the UDP packet and sends an ARP request instead. UDP packets to the destination are discarded until the ARP reply arrives. The instrumentation counter instr_hostUnreach is incremented when an outgoing packet is discarded because of unknown destination MAC address. In this case, the function sendto() does not indicate any error.
2.6.11 ARP packet validation
ARP packets with broadcast or multicast MAC address in the ARP packet source hardware address field are considered invalid. When dynamic ARP is enabled, ANIS ignores such ARP packets.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
ANIS Features, Constraints and Hints 15
The validation is relaxed in the static ARP table configuration. Static ARP table may contain arbitrary MAC addresses and ANIS replies to ARP request with arbitrary source hardware address. If some hosts on the network are configured to use multicast MAC addresses for unicast communication, a static ARP table should be configured in ANIS.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
3 PikeOS Application
3.1 Configuring your Project
In your PikeOS native application project, the option „Anis Socket support“ must be activated in the Project Configura- tor. Activating this option will add the necessary include and library paths to the compilation rules. It will also add the ANIS native library to your application during the linking process.
3.2 Initializing and Using ANIS in your Source Code
To be able to use ANIS in your PikeOS application, the library must first be initialized by calling the anis_init() function. This function takes two parameters:
• the ANIS file provider name.
• a thread number that will be used internally by the ANIS library.
Here is a sample code fragment which shows how to do this:
#include <p4.h> #include <vm.h> #include <p4ext/p4ext_threads.h>
#include <socket.h> /* ANIS header */
/* Include this if you want to use the ANIS instrumentation API */ #include <instr.h>
int main(void) { P4_thr_t thread_no; P4_e_t p4e; int ret;
/* Allocate a thread number for use by ANIS */
thread_no = -1;
p4e = p4ext_thr_num_alloc(&thread_no);
if (p4e != P4_E_OK) {
vm_cprintf("Failed to allocate thread number for ANIS: %d %s\n",
p4e, p4_strerror(p4e));
vm_shutdown(VM_RESPART_MYSELF);
}
/* Initialize ANIS */
/* Change "myanis" to the actual name chosen for the ANIS file provider */
ret = anis_init("myanis", thread_no);
if (ret != ANIS_E_OK) {
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
Limitations 17
vm_cprintf("ANIS init error %d\n", ret);
vm_shutdown(VM_RESPART_MYSELF);
}
/* Application can use ANIS socket API from now on */
...
}
3.3 Limitations
Please note that the Thread Local Storage (TLS) of all threads that use ANIS API must be initialized. The threads blocked in ANIS PikeOS API functions must not be deleted.
3.4 Sample Project
A sample PikeOS demo project for ANIS is provided for the PikeOS native personality. This project could be used as a starting point for cloning, testing or just looking at the code. The base directory for the sample is /opt/pikeos-D5.0/demo/pikeos-native/anis and for the integration project it is /opt/pikeos-D5.0/demo/integration/anis-pikeos-native. The demo anis provides a "mirror" application running on host which echoes packets back to the target. Detailed information on how to clone and setup the demo application can be found within the integration project in the file README.anis.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
4 ANIS PikeOS API Reference
This section presents the data types and functions available in the ANIS PikeOS API.
4.1 Header File
Following headers provide ANIS PikeOS API functions and definitions: #include <instr.h> #include <socket.h>
4.2 AnisSocket
4.2.1 Structure Definitions
4.2.1.1 struct in_addr
Data type to hold an IPv4 address.
Synopsis: struct in_addr { uint32_t s_addr; };
Structure Element Description: s_addr An IPv4 address in network byte order. This member contains an IPv4 address as defined in [RFC-791] or the special address INADDR_ANY in network byte order.
4.2.1.2 struct sockaddr_in
Data type to store an PF_INET socket address.
Synopsis: struct sockaddr_in { sa_family_t sin_family; in_port_t sin_port; struct in_addr sin_addr; char sin_zero[8]; };
Structure Element Description: sin_family The address family this structure belongs to. This member is used to recognize a struct sockaddr_in element casted to struct sockaddr. Its value is always set to PF_INET. sin_port The port part of the address. This member contains the UDP port part of the address in network byte order.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 19
sin_addr The IP part of the address.
This member contains the IP address part of the address in network byte order.
sin_zero Extra padding at the end of the structure.
4.2.1.3 struct sockaddr
Data type to handle addresses in an domain agnostic manner. The struct sockaddr provides an address domain agnostic means to exchange socket addresses with API service calls. ANIS supports only one address domain: IPv4. Addresses for this domain are defined using struct sockaddr_in. This domain specific structure is mapped to a struct sockaddr in API service calls.
See also: struct sockaddr_in
Synopsis: struct sockaddr { sa_family_t sa_family; char sa_data[14]; };
Structure Element Description: sa_family The address family this structure belongs to. sa_data Place holder for the actual data.
4.2.1.4 struct ip_mreq
Data type to handle group membership. The struct ip_mreq provides way to associate multicast group with network interface. This is used to register into a multicast group or drop membership of a multicast group.
Synopsis: struct ip_mreq { struct in_addr imr_multiaddr; struct in_addr imr_interface; };
Structure Element Description: imr_multiaddr Multicast group address the application wants to leave or join. imr_interface IP address identifying a network interface.
4.2.2 Defines
PF_INET
Constant to be used in socket() calls for the socket family.
SOCK_DGRAM
Type of a UDP socket.
Description:
Set the type of a socket in socket() (see section 6.2.4.2) calls. The value SOCK_DGRAM is used to create a socket
for a packet based, unreliable connection like UDP.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
20 ANIS PikeOS API Reference
AF_INET
Constant to be used in the sin_family member of struct sockaddr_in.
Description:
This constant is used to specify the address family "internet".
INADDR_ANY
Constant to be used in bind() to receive datagrams from all interfaces.
Description:
Binding to the special address INADDR_ANY allows a socket to receive datagrams from any configured interface
in the system, including localhost loopback.
SOL_SOCKET
Options for socket level.
IPPROTO_IP
Options for IP level.
SO_TYPE
Get socket type.
SO_RCVBUF
Get or set maximum mbuf usage of a socket for reception.
SO_REUSEADDR
Use of exact address matching at the binding time.
SO_FLUSH_ARP
Force ARP record to flush.
IP_ADD_MEMBERSHIP
Add membership to a multicast group.
IP_DROP_MEMBERSHIP
Drop membership of a multicast group.
IP_MULTICAST_TTL
Set TTL of the multicast messages on the given socket.
IP_MULTICAST_IF
Set outgoing interface for the multicast messages on the given socket.
IP_MULTICAST_LOOP
Set loopback on the outgoing multicast traffic for the given socket.
ANIS_RCVBUF_NO_LIMIT
Special value for the SO_RCVBUF option with the meaning unlimited.
Description:
If the SO_RCVBUF option of a socket is set to this value, there is no limit on the maximum mbuf usage. This is
the default for a newly created socket.
ANIS_MAX_NAMELEN
Maximum length of an ANIS instance name.
MSG_DONTWAIT
Flag used to select nonblocking I/O in sendto() and recvfrom().
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 21
ntohs (x)
Convert a short integer value x from network to host byte order.
Parameters:
x [IN] Short integer value to convert.
Returns:
The function returns the representation of x in host byte order.
ntohl (x)
Convert a long integer value x from network to host byte order.
Parameters:
x [IN] Long integer value to convert.
Returns:
The function returns the representation of x in host byte order.
ntohll (x)
Convert a long long integer value x from network to host byte order.
Parameters:
x [IN] Long Long integer value to convert.
Returns:
The function returns the representation of x in host byte order.
htons (x)
Convert a short integer value x from host to network byte order.
Parameters:
x [IN] Short integer value to convert.
Returns:
The function returns the representation of x in network byte order.
htonl (x)
Convert a long integer value x from host to network byte order.
Parameters:
x [IN] Long integer value to convert.
Returns:
The function returns the representation of x in network byte order.
htonll (x)
Convert a long long integer value x from host to network byte order.
Parameters:
x [IN] Long long integer value to convert.
Returns:
The function returns the representation of x in network byte order.
4.2.3 Data Type Definitions
socklen_t Data type to represent the size of a struct sockaddr data type.
sa_family_t Data type to hold the socket type.
in_port_t Data type to hold a UDP port number.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
22 ANIS PikeOS API Reference
ssize_t Signed data type to hold the size of a message.
This signed integer type is used to store the size of a received message or an error indication.
size_t Unsigned long data type to hold the size of a message.
This unsigned long type is used to store the size of a message to be sent.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 23
4.2.4 Enumerations
Enumeration type anis_error_e
Error return codes of ANIS API functions. The functions of the ANIS API return one of these values to indicate success or failure. All error codes are negative so that they are disjoint from non-negative integers that indicate success in certain services (e.g. socket() (see section 6.2.4.2), recvfrom() (see section 6.2.4.7), and sendto() (see section 4.2.5.5)).
Name Description ANIS_E_OK everything is okay
ANIS_E_AFNOSUPPORT invalid address (protocol) family
ANIS_E_SOCKTNOSUPPORT invalid socket type
ANIS_E_PROTOTYPE invalid protocol
ANIS_E_BUSY socket is already in use or not enough resources
ANIS_E_BADF invalid socket descriptor
ANIS_E_ADDRINUSE address is already in use
ANIS_E_FAULT invalid length value
ANIS_E_ADDRNOTAVAIL invalid IP address
ANIS_E_INVAL invalid argument length
ANIS_E_OPNOTSUPP invalid protocol level
ANIS_E_NOPROTOOPT invalid socket option option
ANIS_E_RANGE oversize length value
ANIS_E_AGAIN could not be done, try again
ANIS_E_MSGSIZE message is greater than buffer
ANIS_E_NO_ENT ANIS instance doesn’t exist
ANIS_E_PERM permission denied
ANIS_E_STATE unbound socket or initialization of ANIS failed
ANIS_E_SYS internal error occurred
ANIS_E_INTR operation was interrupted
ANIS_E_NO_MEM Not enough memory
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
24 ANIS PikeOS API Reference
ANIS_E_NO_FD File descriptor cannot be allocated
ANIS_E_THRACTIVE In the system already exists active thread with the same number
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 25
4.2.5 Functions
4.2.5.1 anis_init
Synopsis:
int anis_init(const char *anisname, P4_uint32_t threadno)
Description: Initialize ANIS API. Initialize a connection to an ANIS instance with the name given in anisname. Internally the ANIS API runs a thread to implement blocking. This thread is also started by this function. The thread number to use is provided in the argument threadno.
Parameters: anisname [IN] Name of an ANIS instance. threadno [IN] Thread number for the internal control thread.
Returns: On success the function returns ANIS_E_OK. If an error occurs, it returns one of the following error codes. ANIS_E_NO_MEM Not enough memory to initialize PikeOS API. ANIS_E_NO_FD Not enough file descriptors. ANIS_E_THRACTIVE Thread with the same ID is already active. ANIS_E_STATE Initialization has already been done. ANIS_E_NO_ENT No ANIS instance anisname exists. Instance of the anisname was not either starter or failed during startup. ANIS_E_PERM No sufficient access right to connect to the ANIS instance. ANIS_E_INVAL The string length of anisname is greater than or equal to ANIS_MAX_NAMELEN. ANIS_E_SYS A call to a PikeOS API function failed.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
26 ANIS PikeOS API Reference
4.2.5.2 socket
Synopsis:
int socket(int domain, int type, int protocol)
Description: Create a new socket. This function creates a new ANIS socket using the parameter domain, type and protocol to specify it. The only valid values are PF_INET for domain, SOCK_DGRAM for type and 0 for protocol.
Parameters: domain [IN] the communication domain; only PF_INET is supported type [IN] the communication semantics; only SOCK_DGRAM is supported protocol [IN] the communication protocol; only 0 is supported.
Returns: On success the function returns a valid socket descriptor that references the created socket. If an error occurs, it returns one of the following negative error codes. ANIS_E_STATE Initialization has not yet been done. ANIS_E_PROTOTYPE type is not set to SOCK_DGRAM ANIS_E_AFNOSUPPORT domain is not set to PF_INET ANIS_E_AFSOCKTNOSUPPORT protocol is not set to 0 ANIS_E_BUSY Reached the limit of 512 sockets open by the application. ANIS_E_BUSY The total number of sockets open by all clients of the ANIS file provider reached the configured limit. ANIS_E_NO_FD Not enough file descriptors. ANIS_E_SYS An internal error occurred or a call to a PikeOS API function failed.
Note: The number of sockets that can be opened simultaneously is limited in multiple ways. If the smallest of these limits is exceeded, socket() (see section 6.2.4.2) will fail and return ANIS_E_BUSY or ANIS_E_NO_FD. The limits are:
• number of sockets configured in the ANIS file provider
• maximum number of file descriptors of the caller’s partition (a file descriptor is needed for each open socket)
• at most 512 open sockets are supported by the PikeOS ANIS API library
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 27
4.2.5.3 bind
Synopsis:
int bind(int sock, struct sockaddr *address, socklen_t address_len)
Description: Bind a socket to an address. Bind the given socket to the given address. Bind to INADDR_ANY address results to socket bound to all configured interfaces including localhost interface.
Parameters: sock [IN] the socket descriptor to bind address [IN] the address to which to bind the socket address_len [IN] the size in bytes of the object referenced by address
Returns: On success the function returns ANIS_E_OK. ANIS_E_ADDRINUSE another socket is already bound to address ANIS_E_INVAL address_len is not equal to the size of struct sockaddr_in ANIS_E_INVAL the socket is already bound ANIS_E_AFNOSUPPORT the sin_family member of address is not PF_INET ANIS_E_ADDRNOTAVAIL the IP address specified in address does neither match the configured IP address nor INADDR_ANY ANIS_E_BADF sock is not a valid socket descriptor ANIS_E_SYS an internal error occurred or a call to a PikeOS API function failed ANIS_E_STATE ANIS wasn’t initialized.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
28 ANIS PikeOS API Reference
4.2.5.4 recvfrom
Synopsis:
ssize_t recvfrom(int sock, void *buffer, size_t length, int flags, struct sockaddr *address, socklen_t *address_len)
Description: Retrieve a message from a socket. Dequeue the oldest message from the sockets sock message queue and return its first N bytes in buffer, where N is the lesser of the value provided in length and the message size. If the message queue is currently empty and the MSG_DONTWAIT flag is not set in flags, recvfrom() (see section 6.2.4.7) blocks until a message is received or an error occurs. If the message queue is currently empty and the MSG_DONTWAIT flag is set in flags, recvfrom() (see section 6.2.4.7) returns immediately with error ANIS_E_EAGAIN. If the output parameter address is not NULL, the source address of the received message is returned in this buffer and address_len is set to the length of the value written into address. If the application does not need the source address of the message, it may set address and address_len to NULL.
Parameters: sock [IN] the socket descriptor to be read from buffer [OUT] the output buffer used to store the received message length [IN] the size of the buffer provided in buffer flags [IN] receive semantics; either zero or MSG_DONTWAIT address [OUT] the output buffer used to store the source address of the received message address_len [INOUT] the length of the buffer provided in address when called; the length of the address upon return
Returns: If a message was successfully received that did fit into the provided buffer, recvfrom() (see section 6.2.4.7) returns the size of the message in bytes. If the message did not fit completely into the buffer, recvfrom() (see section 6.2.4.7) returns ANIS_E_MSGSIZE. In this case only the first length bytes are available to the caller. ANIS_E_MSGSIZE the message is longer than length bytes. ANIS_E_INTR sock is closed whilst blocking ANIS_E_AGAIN the message queue of sock is empty and the MSG_DONTWAIT flag is set in flags ANIS_E_STATE sock is not bound ANIS_E_RANGE length is greater than the maximum message size of 65507 bytes ANIS_E_INVAL address_len is less than the size, in bytes, of a struct sockaddr_in ANIS_E_INVAL unsupported flags are set in flags ANIS_E_BADF sock is not a valid socket descriptor ANIS_E_SYS an internal error occurred or a call to a PikeOS API function failed. The reasons include uninitialized thread local storage or message not entirely mapped.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 29
4.2.5.5 sendto
Synopsis:
ssize_t sendto(int sock, const void *message, size_t length, int flags, struct sockaddr *dest_addr, socklen_t dest_len)
Description: Send a message. The function sendto() (see section 4.2.5.5) sends the message of length length given in message using the socket sock to the destination dest_addr. If the peer address address is the limited broadcast address (i.e. 255.255.255.255), the message is send to the directed broadcast address of the local network the socket is bound to. If the sending socket is bound to INADDR_ANY the outgoing device is selected by the ANIS. In case of multicast message the outgoing interface can be set via IP_MULTICAST_IF, or the interface is selected based on the group membership registration via IP_ADD_MEMBERSHIP. If none of above succeeds the message is sent out via 1st configured interface. If ANIS does not have sufficient resources to send the message and the MSG_DONTWAIT flag is not set in flags, the sendto() (see section 4.2.5.5) function will block until resources become available. If the flag is set, the function returns immediately in this case with an error.
Parameters: sock [IN] the socket descriptor to be used for sending message [IN] the buffer used to store the message to be send length [IN] the size of the message stored in message flags [IN] send semantics; either zero or MSG_DONTWAIT dest_addr [IN] the destination address of the message dest_len [IN] the length in bytes of the dest_addr buffer
Returns: On success sendto() (see section 4.2.5.5) returns the number of bytes sent. ANIS_E_SYS an internal error occurred or a call to a PikeOS API function failed. The reasons include uninitialized thread local storage or message not entirely mapped. ANIS_E_BADF sock is not a valid socket descriptor ANIS_E_INTR sock is closed whilst blocking ANIS_E_STATE sock is not bound ANIS_E_INVAL unsupported flags are set in flags ANIS_E_FAULT dest_len is not equal to the size, in bytes, of a struct sockaddr_in ANIS_E_RANGE length is greater than the maximum message size of 65507 bytes ANIS_E_AGAIN ANIS does not have sufficient resource to send the message and the MSG_DONTWAIT flag is set in flags
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
30 ANIS PikeOS API Reference
4.2.5.6 getsockname
Synopsis:
int getsockname(int sock, struct sockaddr *address, socklen_t *address_len)
Description: Retrieve local address of socket. Retrieve the local address the socket sock is bound to and store it in address. The parameter address_len must contain the length of the buffer provided in address when this function is called. If the given socket is bound, getsockname() (see section 6.2.4.6) will set address_len to the amount of bytes written into address. If the given socket is not bound, getsockname() (see section 6.2.4.6) will set address_len to zero.
Parameters: sock [IN] the socket descriptor whose local address shall be retrieved address [OUT] the local address of the socket sock address_len [INOUT] the length of the buffer provided in address when called; the length of the address upon return (if bound) or 0 (if not bound)
Returns: On success the function returns ANIS_E_OK. ANIS_E_INVAL address_len is less than the size, in bytes, of a struct sockaddr_in. ANIS_E_BADF sock is not a valid socket descriptor ANIS_E_BADF ANIS wasn’t initialized ANIS_E_SYS an internal error occurred or a call to a PikeOS API function failed
See also: bind() (see section 6.2.4.3)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 31
4.2.5.7 getsockopt
Synopsis:
int getsockopt(int sock, int level, int option_name, void *option_value, socklen_t *option_len)
Description: Retrieve socket options. Retrieve options of a socket. Upon success 0 is returned. If an error occurred the function returns -1 and sets errno. Parameter level defines protocol level. Two groups SOL_SOCKET and IPPROTO_IP are supported. Supported option_names for SOL_SOCKET are following • SO_TYPE: The type of the socket; with ANIS this is always SOCK_DGRAM. • SO_RCVBUF: The current limit of the sockets receive buffer in bytes.
Supported option_names for IPPROTO_IP are following.
• IP_MULTICAST_TTL: Get the time-to-live value of outgoing multicast packets for this socket. Argument is an integer. • IP_MULTICAST_LOOP: Get boolean integer argument that determines whether sent multicast packets should be looped back to the local socket.
Parameters: sock [IN] the socket descriptor whose options shall be retrieved level [IN] the protocol level; only SOL_SOCKET is supported option_name [IN] which option to retrieve; supported are SO_TYPE and SO_RCVBUF option_value [OUT] the value of the option option_len [INOUT] size of the buffer passed in option_value on input; size of the retrieved value on output
Returns: On success the function returns ANIS_E_OK. ANIS_E_OPNOTSUPP level is not SOL_SOCKET ANIS_E_NOPROTOOPT option_name is neither SO_RCVBUF nor SO_TYPE ANIS_E_INVAL the input value of option_len is less than the size of the output option value ANIS_E_BADF sock is not a valid socket descriptor ANIS_E_BADF ANIS wasn’t initialized ANIS_E_SYS an internal error occurred or a call to a PikeOS API function failed
See also: setsockopt() (see section 6.2.4.5)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
32 ANIS PikeOS API Reference
4.2.5.8 setsockopt
Synopsis:
int setsockopt(int sock, int level, int option_name, const void *option_value, socklen_t option_len)
Description: Set socket options. Set options of a socket. Parameter level defines protocol level. Two groups SOL_SOCKET and IPPROTO_IP are supported. Supported options for SOL_SOCKET are following. • SO_RCVBUF: If the value provided in the int object referenced by option_value is ANIS_RCVBUF_NO_LIMIT the limit of the sockets socket receive buffer is set to unlimited. Otherwise it is set to the given value in bytes, rounded up to a multiple of the MTU. If zero value is provided as input value no reception buffers are assigned to the socket. Each time packet is received the whole MTU size (one mbuf) is taken from the pool of assigned buffers. In case of setting limit to the lower value than the count of the currently occupied reception buffers, no buffer is released, and the limit is applied to all the new messages. • SO_REUSEADDR: Indicates that the rules used in validating addresses supplied in a bind() (see section 6.2.4.3) call should allow reuse of local addresses. For PF_INET sockets this means that a socket may always bind. Argument is an integer boolean flag. • SO_FLUSH_ARP: Flush ARP record for the given IP together with all the packets scheduled to send to the destination IP. Expected is struct in_addr value in the network order representing IP. If there is already ongoing write of the packet to the Ethernet driver to the destination IP, the packet is not dropped, but it is sent with the resolved MAC address from the time before ARP record flush. The SO_FLUSH_ARP option is an ANIS-specific addition to the socket API and may be disabled by a configuration option.
In case several sockets are being bind to the same IP:PORT, SO_REUSEADDR needs to be set latest before 2nd bind to the 2nd socket. If there are several sockets bound to the same IP:PORT pair, the unicast messages are delivered only to the one target socket, the first one bound. And if there are not enough buffers available due to reception buffer limit set, the message is discarded even there are other sockets with valid IP:PORT. In case of Multicast traffic the message is delivered to all the socket within the same group and with sufficient reception buffers. In case of the Broadcast traffic the message is delivered to all the sockets bound to the target segment IP:PORT and with sufficient reception buffers. Supported options for IPPROTO_IP are following.
• IP_ADD_MEMBERSHIP: Join a multicast group. Argument is an ip_mreq structure. Local interface IP or IN-
ADDR_ANY can be provided as interface address. If INADDR_ANY is used 1st configured interface in the system
is used as outgoing device. This can be later changed by the IP_MULTICAST_IF option. Each unique group can be
added just once to the socket.
• IP_DROP_MEMBERSHIP: Leave a multicast group. Argument is an ip_mreq structure, where member "imr_interface"
is ignored.
• IP_MULTICAST_TTL: Set the time-to-live value of outgoing multicast packets for this socket. It is very important for
multicast packets to set the smallest TTL possible. The default is 1 which means that multicast packets don’t leave the
local network unless the user program explicitly requests it. Argument is an integer.
• IP_MULTICAST_IF: Set the local device for a multicast socket. Argument is an ip_mreq structure, the same one as
for IP_ADD_MEMBERSHIP. Only member ’imr_interface’ needs to be specified, other members are ignored.
• IP_MULTICAST_LOOP: Set a boolean integer argument that determines whether sent multicast packets should be
looped back to the local sockets. Multicast loop is enabled by default on newly created sockets.
Example:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 33
sockA (MC loop false, group X), SockB (MC loop true, group X) > sendto(sockA) > Message is not received by any
socket.
sockA(MC loop false, group X), SockB (MC loop true, group X) > sendto(sockB) > Messages is received back by sockB
and SockA sockets.
Parameters: sock [IN] the socket descriptor whose options shall be set level [IN] the protocol level option_name [IN] which option to set option_value [IN] the new value of the option option_len [IN] size of the buffer passed in option_value
Returns: On success the function returns ANIS_E_OK ANIS_E_OPNOTSUPP level is not SOL_SOCKET nor IPPROTO_IP ANIS_E_NOPROTOOPT option_name is none of supported ones ANIS_E_INVAL option_len is not equal to the size of bytes of the object referenced by option_value. Or the provided input values are out of allowed input range. Or socket is already member of the provided group. Or there is no space for more groups to be added. Or there is no ARP record for given IP to FLUSH. Or the ARP table is static. ANIS_E_PERM SO_FLUSH_ARP is not allowed by the configuration. ANIS_E_BADF sock is not a valid socket descriptor ANIS_E_BADF ANIS wasn’t initialized ANIS_E_SYS an internal error occurred or a call to a PikeOS API function failed
See also: getsockopt() (see section 6.2.4.4)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
34 ANIS PikeOS API Reference
4.2.5.9 socket_close
Synopsis:
int socket_close(int sock)
Description: Close a socket. This function frees the socket object allocated to the socket in the ANIS API and sends a socket close request to ANISFP, which will also release all resources allocated to the socket.
Parameters: sock [IN] the socket to close
Returns: On success the function returns ANIS_E_OK. ANIS_E_BADF sock is not a valid socket descriptor ANIS_E_BADF ANIS wasn’t initialized ANIS_E_SYS an internal error occurred or a call to a PikeOS API function failed
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisInstr 35
4.3 AnisInstr
4.3.1 Structure Definitions
4.3.1.1 struct anis_instr_intf_stat_s
ANIS interface specific instrumentation API structure. This data structure is used to communicate network interface statistics to an application.
Synopsis:
struct anis_instr_intf_stat_s { uint32_t intf_enabled; uint32_t intf_ip_address; uint32_t intf_netmask; uint8_t intf_mac_address[6]; uint32_t intf_link_status; uint32_t intf_link_speed; uint32_t instr_fragTimeout; uint32_t instr_fragSpace; uint32_t instr_fragError; uint32_t instr_fragOffset; uint32_t instr_sockRecvBuf; uint32_t instr_icmpType; uint32_t instr_icmpFrag; uint32_t instr_icmpSum; uint32_t instr_igmpType; uint32_t instr_igmpFrag; uint32_t instr_igmpSum; uint32_t instr_ipSum; uint32_t instr_ipHeaderConstant; uint32_t instr_ipSize; uint32_t instr_ipProtocol; uint32_t instr_noSocket; uint32_t instr_badIP; uint32_t instr_hostUnreach; uint32_t instr_arpProtocol; uint32_t instr_txDrop; };
Structure Element Description: intf_enabled Status of the interface configuration Indication of the interface configuration status. If the interface is configured then 1 is stored in the variable. Otherwise 0. intf_ip_address The configured IP address of the interface. The IP address is stored in the network byte order. intf_netmask The configured network mask of the interface. The IP address is stored in the network byte order. intf_mac_address The MAC address of the interface. The field is set to zero for local loopback interface. intf_link_status Current interface link status. Indication of the interface link status from the underlying ethernet driver. The value 0 indicates link down, the value 1 link up. This member is set to 0 for the localhost loopback interface. intf_link_speed Current interface link speed.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
36 ANIS PikeOS API Reference
Indication of the interface link speed from the underlying ethernet driver in megabits per second. This member is
set to 0 for the localhost loopback interface.
instr_fragTimeout The number of FRAG_TIMEOUT class errors.
It is incremented if the fragmentation timeout between reception of two consecutive fragments belonging to the
same IP datagram is exceeded.
instr_fragSpace The number of FRAG_SPACE class errors.
It is incremented if the maximum number of concurrent fragmented IP datagrams supported is exceeded.
instr_fragError The number of FRAG_ERROR class errors.
It is incremented if fragments are received out of order and either no previous fragment of the datagram was
received or the previous received fragments were dropped due to other constraints (e.g. time out).
instr_fragOffset The number of FRAG_OFFSET class errors.
It is incremented if fragments are received out of order and at least one previous fragment was received.
instr_sockRecvBuf The number of SOCK_RECVBUF class errors.
It is incremented if a IP datagram is received which would cause the destination socket to exceed its receive buffer
size limit.
instr_icmpType The number of ICMP_TYPE class errors.
It is incremented if an ICMP datagram is received with invalid or unsupported values in the ICMP "Type" or "Code"
header fields.
instr_icmpFrag The number of ICMP_FRAG class errors.
It is incremented if an ICMP datagram is received with the fragmentation bit set in the IP header.
instr_icmpSum The number of ICMP_CHKSUM class errors.
It is incremented if an ICMP datagram with invalid checksum is received.
instr_igmpType The number of IGMP_TYPE class errors.
It is incremented if an IGMP datagram is received with invalid or unsupported values in the IGMP "Type" header
field.
instr_igmpFrag The number of IGMP_FRAG class errors.
It is incremented if an IGMP datagram is received with the fragmentation bit set in the IP header.
instr_igmpSum The number of IGMP_CHKSUM class errors.
It is incremented if an IGMP datagram with invalid checksum is received.
instr_ipSum The number of IP_CHKSUM class errors.
It is incremented if an IP datagram with invalid checksum is received.
instr_ipHeaderConstant The number of IP_HDR class errors.
It is incremented if an IP datagram with invalid or unsupported values in the header (except those covered by
IP_SIZE and IP_PROTO) is received.
instr_ipSize The number of IP_SIZE class errors.
It is incremented if an IP datagram with an invalid value in the "Total Length" header field is received.
instr_ipProtocol The number of IP_PROTO class errors.
It is incremented if an IP datagram with invalid or unsupported value in the IP header "Protocol" field is received.
instr_noSocket The number of NO_SOCK class errors.
It is incremented if a UDP datagram is received, but no socket is bound to the destination address.
instr_badIP The number of BAD_IP class errors.
It is incremented if an IP datagram is received, but the destination address does match neither the configured
address nor the broadcast address. It is also incremented if the source address is a broadcast address, multicast
address or a local loopback address.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisInstr 37
instr_hostUnreach The number of HOST_UNREACHABLE class errors
It is incremented if the application tried to send data to a host, which is not reachable.
instr_arpProtocol The number of ARP_PROTO class errors
It is incremented if the ANISFP stack receives ARP packet with unexpected content in the ARP header.
instr_txDrop The number of TX_DROP class errors
It is incremented if the ethernet driver reports an error in transmit (vm_write()) operation. This counter is not used
if the txErrorFatal configuration property is true.
Associated Data Type
anis_instr_intf_stat_t ANIS interface specific instrumentation API structure.
4.3.1.2 struct anis_instr_stat_s
ANIS instrumentation API data structure. This data structure is used to communicate network interface statistics to an application.
Synopsis: struct anis_instr_stat_s { uint32_t instr_sendNoSrc; uint32_t instr_udpLength; uint32_t instr_udpSum; uint32_t instr_socketList; anis_instr_intf_stat_t intf[ANIS_ALL_INTF]; };
Structure Element Description: instr_sendNoSrc The number of SEND_NOSRC class errors. It is incremented if the application tried to send on an unbound socket. instr_udpLength The number of UDP_LENGTH class errors It is incremented if a UDP datagram is reassembled and some data left in the buffer for reassembly. instr_udpSum The number of UDP_CHKSUM class errors It is incremented if a UDP datagram with invalid checksum is received. In the certified ANIS variant this is only checked for UDP datagrams that are fragmented at the IP level. instr_socketList The number of SOCKET_LIST class errors. ANIS reserves internal memory to store association between multicast packets and receiving sockets. If a packet is not delivered to a socket because ANIS ran out of memory, this counter is incremented. intf Interface specific counters Field of anis_instr_intf_stat_t structures to access interface specific counters.
Associated Data Type
anis_instr_stat_t ANIS instrumentation API data structure.
4.3.2 Defines
ANIS_ALL_INTF
Maximum number of Ethernet interfaces including localhost loopback.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
38 ANIS PikeOS API Reference
4.3.3 Data Type Definitions
anis_instr_e_t ANIS instrumentation API service return codes.
anis_instr_intf_stat_t ANIS interface specific instrumentation API structure.
This data structure is used to communicate network interface statistics to an application.
anis_instr_stat_t ANIS instrumentation API data structure.
This data structure is used to communicate network interface statistics to an application.
anis_instr_t ANIS instrumentation API handle.
This data type is used in the ANIS instrumentation API for handles that identify the open instance of the instru-
mentation channel.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisInstr 39
4.3.4 Enumerations
Enumeration type anis_instr_e
ANIS instrumentation API service return codes.
Name Description ANIS_INSTR_E_OK The instrumentation API call was successful.
ANIS_INSTR_E_INVAL The instrumentation API call failed due to invalid arguments.
ANIS_INSTR_E_PERM The instrumentation API call failed due to insufficient access rights.
ANIS_INSTR_E_NO_MEM The instrumentation API call failed due to missing resources.
ANIS_INSTR_E_NO_ENT The instrumentation API call failed as the given ANIS instance does not exist.
ANIS_INSTR_E_SYS The instrumentation API call failed due to an internal error.
ANIS_INSTR_E_BUSY The instrumentation read channel is already open.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
40 ANIS PikeOS API Reference
4.3.5 Functions
4.3.5.1 anis_instr_open
Synopsis:
anis_instr_e_t anis_instr_open(const char *name, anis_instr_t *handle)
Description: Open an instrumentation connection. This function opens an instrumentation connection on an ANIS instance, specified by parameter name.
Parameters: name [IN] Name of ANIS instance. handle [OUT] Handle to ANIS instance.
Returns: On success, the function returns ANIS_INSTR_E_OK and a valid handle in parameter handle. ANIS_INSTR_E_NO_ENT No ANIS instance with the specified name exists. ANIS_INSTR_E_NO_PERM The caller does not have sufficient rights to access the instrumentation statistics. ANIS_INSTR_E_NO_MEM The caller does not have sufficient resources to establish a connection with the ANIS instance. ANIS_INSTR_E_INVAL The length of name exceeds VM_MAX_PATHNAME_LEN. ANIS_INSTR_E_SYS The connection with the ANIS instance failed do to internal reasons.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisInstr 41
4.3.5.2 anis_instr_close
Synopsis:
anis_instr_e_t anis_instr_close(anis_instr_t *handle)
Description: Close the instrumentation connection. This function closes the instrumentation connection with the ANIS instance referenced by parameter handle.
Parameters: handle [IN] Handle to ANIS instance.
Returns: On success, the function returns ANIS_INSTR_E_OK. ANIS_INSTR_E_INVAL handle is not a valid ANIS instrumentation handle. ANIS_INSTR_E_SYS The connection with the ANIS instance fails.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
42 ANIS PikeOS API Reference
4.3.5.3 anis_instr_read
Synopsis:
anis_instr_e_t anis_instr_read(anis_instr_t *handle, anis_instr_stat_t *stats)
Description: Read instrumentation data. This function retrieves instrumentation statistics from the ANIS instance referenced by parameter handle. It returns statistics for all the interfaces including localhost loopback. Valid records are indicated by the value ’1’ in the intf_enabled member. The order of the counters is the same as order of configured interfaces in the system. Localhost loopback is all the time the last one from the group of enabled interfaces. Example of "intf_enabled" values based on the configured interfaces: Enabled interfaces (1)+ localhost loopback: 1 1 0 0 0 0 0 0 Enabled interfaces (3)+ localhost loopback: 1 1 1 1 0 0 0 0 Enabled interfaces (7)+ localhost loopback: 1 1 1 1 1 1 1 1
Parameters: handle [IN] Handle to ANIS instance. stats [OUT] Pointer to structure to receive the statistics.
Returns: On success, the function returns ANIS_INSTR_E_OK. ANIS_INSTR_E_INVAL handle is not a valid ANIS instrumentation handle. ANIS_INSTR_E_SYS The connection with the ANIS instance fails.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
5 POSIX Application
5.1 Configuring your Project
To be able to use ANIS in your POSIX application, enable the parameter „ANIS FP support“ in the Project Configurator. When this option is selected, the required library path is added to the standard flags for compilation and the library needed for ANIS is automatically added to the list of libraries during the linking process.
5.2 Configuring Project Resources
ANIS needs some resources to be granted to start and operate properly. To do that, enable „System Parameters“ in your integration project at „Application -> POSIX Process -> Tunable Parameters“ menu. If the resources are not granted properly the ANIS will exit with Input/output error code. The following parameters needs to be set properly:
• Maximum number of file descriptors (fds): Value shall be calculated as (minimum fds for POSIX) + 4. Minimum value
of file descriptors for the POSIX can be found in the installed POSIX documentation.
5.3 Initializing and Using ANIS in your Source Code
Before using the ANIS functionality in your POSIX code, make sure that the necessary header files are included, and that the initialization function is called. Here is a sample code fragment which shows how to do this :
#include <stdio.h> #include <socket.h> /* ANIS header */
/* Include this if you want to use the ANIS instrumentation API */ #include <instr.h>
int main(void) { int rc; int fd;
printf("Initializing ANIS\n");
/* Initialize ANIS */
/* Change "myanis" to the actual name chosen for the ANIS file provider */
rc = anis_init("myanis");
/* Application can use ANIS socket API from now on */
...
}
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
44 POSIX Application
5.4 Limitations
Please note that POSIX socket functions are not cancellation safe. Applications using thread cancellation should disable cancellation prior to entering socket services.
5.5 Sample Projects
5.5.1 Unicast
A sample Unicast PikeOS demo project for ANIS is provided for the POSIX personality. This project could be used as a starting point for cloning, testing or just looking at the code. The base directory for the sample application project is /opt/pikeos-D5.0/demo/posix/anis and for the integration project it is /opt/pikeos-D5.0/demo/integration/anis-posix. The demo anis provides a "mirror" application running on host which echoes packets back to the target. Detailed information on how to clone and setup the demo application can be found within the integration project in the file README.anis.
5.5.2 Multicast
A sample multicast PikeOS demo project for ANIS is provided for the POSIX personality. The base directory for the sample application project is /opt/pikeos-D5.0/demo/posix/anis-multicast. It is intended to be used with the integration project /opt/pikeos-D5.0/demo/integration/anis-posix. The demo application is also provided in compiled form accompanied with a dom file to demonstrate usage component dependencies in the project configurator. The dom and component files are stored in the directory /opt/pikeos-D5.0///posix/demo/anis-multicast. Detailed information on how to setup the demo application can be found in the file README.demo within the application project directory.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
6 ANIS POSIX API Reference
This section presents the data types and functions available in the ANIS POSIX API.
6.1 Header File
Following headers provide ANIS POSIX API functions and definitions: #include <instr.h> #include <socket.h>
6.2 AnisSocket
6.2.1 Structure Definitions
6.2.1.1 struct fd_set
Data type to represent a set of sockets. The data type fd_set is able to represent an set of sockets with values in the range zero to FD_SETSIZE.
Associated Data Type
fd_set Data type to represent a set of sockets.
6.2.1.2 struct in_addr
Data type to hold an IPv4 address.
Synopsis: struct in_addr { uint32_t s_addr; };
Structure Element Description: s_addr An IPv4 address in network byte order. This member contains an IPv4 address as defined in [RFC-791] or the special address INADDR_ANY in network byte order.
6.2.1.3 struct sockaddr_in
Data type to store an PF_INET socket address.
Synopsis: struct sockaddr_in { sa_family_t sin_family; in_port_t sin_port; struct in_addr sin_addr;
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
46 ANIS POSIX API Reference
char sin_zero[8];
};
Structure Element Description: sin_family The address family this structure belongs to. This member is used to recognize a struct sockaddr_in element casted to struct sockaddr. Its value is always set to PF_INET. sin_port The port part of the address. This member contains the UDP port part of the address in network byte order. sin_addr The IP part of the address. This member contains the IP address part of the address in network byte order. sin_zero Extra padding at the end of the structure.
6.2.1.4 struct sockaddr
Data type to handle addresses in an domain agnostic manner. The struct sockaddr provides an address domain agnostic means to exchange socket addresses with API service calls. ANIS supports only one address domain: IPv4. Addresses for this domain are defined using struct sockaddr_in. This domain specific structure is mapped to a struct sockaddr in API service calls.
See also: struct sockaddr_in
Synopsis:
struct sockaddr { sa_family_t sa_family; char sa_data[14]; };
Structure Element Description: sa_family The address family this structure belongs to. sa_data Place holder for the actual data.
6.2.1.5 struct ip_mreq
Data type to handle group membership. The struct ip_mreq provides way to associate multicast group with network interface. This is used to register into a multicast group or drop membership of a multicast group.
Synopsis:
struct ip_mreq { struct in_addr imr_multiaddr; struct in_addr imr_interface; };
Structure Element Description: imr_multiaddr Multicast group address the application wants to leave or join. imr_interface IP address identifying a network interface.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 47
6.2.2 Defines
ANIS_NOERROR
API services return code in case of a successful return.
ANIS_ERROR
API services return code if an error occurred.
FD_SETSIZE
Size of the set fd_set.
Description:
The set implemented using data type fd_set is able to contain any subset of the set of socket descriptors with
value smaller than FD_SETSIZE: x| 0 <= x < FD_SETSIZE.
FD_CLR (fd, fdset)
Remove a socket from a set of socket descriptors.
Description:
Remove the socket descriptor fd from the set fdset. The value of the fd argument must be in the range 0 to
FD_SETSIZE.
FD_ISSET (fd, fdset)
Check if a socket is in a set of socket descriptors.
Description:
Check if the socket descriptor given in fd is part of the set fdset.
Returns:
A nonzero value if the socket descriptor fd is part of fdset and zero otherwise.
FD_SET (fd, fdset)
Add a socket to a set or socket descriptors.
Description:
Add the socket descriptor given in fd to the set fdset.
FD_ZERO (fdset)
Clear a set of socket descriptors.
Description:
Initialize the socket descriptor set fdset to empty.
ntohs (x)
Convert a short integer to host byte order.
Description:
The short integer value x is converted from network to host byte order.
Parameters:
x [IN] the short integer value to convert
Returns:
The function returns the representation of x in host byte order.
ntohl (x)
Convert a long integer to host byte order.
Description:
The long integer value x is converted from network to host byte order.
Parameters:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
48 ANIS POSIX API Reference
x [IN] the long integer value to convert
Returns:
The function returns the representation of x in host byte order.
ntohll (x)
Convert a long long integer to host byte order.
Description:
The long long integer value x is converted from network to host byte order.
Parameters:
x [IN] the long long integer value to convert
Returns:
The function returns the representation of x in host byte order.
htons (x)
Convert a short integer to network byte order.
Description:
The short integer value x is converted from host to network byte order.
Parameters:
x [IN] the short integer value to convert
Returns:
The function returns the representation of x in network byte order.
htonl (x)
Convert a long integer to network byte order.
Description:
The long integer value x is converted from host to network byte order.
Parameters:
x [IN] the long integer value to convert
Returns:
The function returns the representation of x in network byte order.
htonll (x)
Convert a long long integer to network byte order.
Description:
The long long integer value x is converted from host to network byte order.
Parameters:
x [IN] the long long integer value to convert
Returns:
The function returns the representation of x in network byte order.
PF_INET
Constant to be used in socket() calls for the socket family.
SOCK_DGRAM
Type of a UDP socket.
Description:
Set the type of a socket in socket() (see section 6.2.4.2) calls. The value SOCK_DGRAM is used to create a socket
for a packet based, unreliable connection like UDP.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 49
AF_INET
Constant to be used in the sin_family member of struct sockaddr_in.
Description:
This constant is used to specify the address family "internet".
INADDR_ANY
Constant to be used in bind() to receive datagrams from all interfaces.
Description:
Binding to the special address INADDR_ANY allows a socket to receive datagrams from any configured interface
in the system, including localhost loopback.
SOL_SOCKET
Options for socket level.
IPPROTO_IP
Options for IP level.
SO_TYPE
Get socket type.
SO_RCVBUF
Get or set maximum mbuf usage of a socket for reception.
SO_REUSEADDR
Use of exact address matching at the binding time.
SO_FLUSH_ARP
Force ARP record to flush.
IP_ADD_MEMBERSHIP
Add membership to a multicast group.
IP_DROP_MEMBERSHIP
Drop membership of a multicast group.
IP_MULTICAST_TTL
Set TTL of the multicast messages on the given socket.
IP_MULTICAST_IF
Set outgoing interface for the multicast messages on the given socket.
IP_MULTICAST_LOOP
Set loopback on the outgoing multicast traffic for the given socket.
ANIS_RCVBUF_NO_LIMIT
Special value for the SO_RCVBUF option with the meaning unlimited.
Description:
If the SO_RCVBUF option of a socket is set to this value, there is no limit on the maximum mbuf usage. This is
the default for a newly created socket.
ANIS_MAX_NAMELEN
Maximum length of an ANIS instance name.
MSG_DONTWAIT
Flag used to select nonblocking I/O in sendto() and recvfrom().
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
50 ANIS POSIX API Reference
6.2.3 Data Type Definitions
fd_set Data type to represent a set of sockets.
The data type fd_set is able to represent an set of sockets with values in the range zero to FD_SETSIZE.
socklen_t Data type to represent the size of a struct sockaddr data type.
sa_family_t Data type to hold the socket type.
in_port_t Data type to hold a UDP port number.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 51
6.2.4 Functions
6.2.4.1 anis_init
Synopsis:
int anis_init(const char *anisname)
Description: Initialize ANIS API. Initialize a connection to an ANIS instance with the name given in anisname. Upon success it returns 0. If an error occurred, it returns -1 and sets errno.
Parameters: anisname [IN] Name of the ANIS instance to connect to.
Returns: On success, the function returns 0.If an error occurred, it returns -1 and sets errno to the following values. ENOMEM not enough memory for the ANIS POSIX application to initialize ENOKMEM Not enough kernel memory available in the partition to create threads. ENOSPC not enough semaphores available for the initialization EINVAL the length of anisname is greater than or equal to ANIS_MAX_NAMELEN ENOENT no ANIS instance anisname exists EACCES the caller does not have sufficient rights to connect to the ANIS instance anisname EPERM the connection with the ANIS instance anisname has already been initialized by a successful call to anis_init() (see section 6.2.4.1) EIO an internal error occurred
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
52 ANIS POSIX API Reference
6.2.4.2 socket
Synopsis:
int socket(int domain, int type, int protocol)
Description: Create a new socket. Create a new ANIS socket and return a valid socket descriptor for it. The only supported arguments are domain PF_INET, type SOCK_DGRAM, and protocol 0.
Pre-Conditions: The ANIS API must have been initialized successfully using anis_init() (see section 6.2.4.1).
Parameters: domain [IN] the communication domain; only PF_INET is supported type [IN] the communication semantics; only SOCK_DGRAM is supported protocol [IN] the communication protocol; only 0 is supported.
Returns: On success, the function returns a valid socket descriptor that references the created socket. If an error occurred, it returns -1 and sets errno to the following values. EAFNOSUPPORT domain is not set to PF_INET EPROTOTYPE type is not set to SOCK_DGRAM EPROTONOSUPPORT protocol is not set to 0 EMFILE ANIS does not have sufficient resources to create a new socket EIO an internal error occurred
Note: The number of sockets that can be opened simultaneously is limited in multiple ways. If the smallest of these limits is exceeded, socket() (see section 6.2.4.2) will fail and set errno to EMFILE. The limits are:
• ANIS itself has only a limited amount of sockets
• for each socket a file is opened and the PSSW and POSIX support only a limited amount of open files
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 53
6.2.4.3 bind
Synopsis:
int bind(int sock, struct sockaddr *address, socklen_t address_len)
Description: Bind a socket to an address. Bind the given socket to the given address. Upon success 0 is returned. If an error occurred the function returns -1 and sets errno. Bind to INADDR_ANY address results to socket bound to all configured interfaces including localhost interface.
Pre-Conditions: The ANIS API must have been initialized successfully using anis_init() (see section 6.2.4.1).
Parameters: sock [IN] the socket descriptor to bind address [IN] the address to which to bind the socket address_len [IN] the size in bytes of the object referenced by address
Returns: On success, the function returns 0. EADDRINUSE another socket is already bound to address EINVAL address_len is not equal to the size of struct sockaddr_in EBADF sock is not a valid socket descriptor EAFNOSUPPORT the sin_family member of address is not PF_INET EINVAL the socket is already bound EADDRNOTAVAIL the IP address specified in address does neither match the configured IP address nor INADDR_ANY EIO an internal error occurred
See also: getsockname() (see section 6.2.4.6)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
54 ANIS POSIX API Reference
6.2.4.4 getsockopt
Synopsis:
int getsockopt(int sock, int level, int option_name, void *option_value, socklen_t *option_len)
Description: Retrieve socket options. Retrieve options of a socket. Upon success 0 is returned. If an error occurred the function returns -1 and sets errno. Parameter level defines protocol level. Two groups SOL_SOCKET and IPPROTO_IP are supported. Supported option_names for SOL_SOCKET are following • SO_TYPE: The type of the socket; with ANIS this is always SOCK_DGRAM. • SO_RCVBUF: The current limit of the sockets receive buffer in bytes.
Supported option_names for IPPROTO_IP are following.
• IP_MULTICAST_TTL: Get the time-to-live value of outgoing multicast packets for this socket. Argument is an integer.
• IP_MULTICAST_LOOP: Get boolean integer argument that determines whether sent multicast packets should be
looped back to the local socket.
Pre-Conditions: The ANIS API must have been initialized successfully using anis_init() (see section 6.2.4.1).
Parameters: sock [IN] the socket descriptor whose options shall be retrieved level [IN] the protocol level option_name [IN] which option to retrieve option_value [OUT] the value of the option option_len [INOUT] size of the buffer passed in option_value on input; size of the retrieved value on output
Returns: On success, the function returns 0. EOPNOTSUPP level is not SOL_SOCKET or IPPROTO_IP ENOPROTOOPT option_name is neither SO_RCVBUF nor SO_TYPE EBADF sock is not a valid socket descriptor EINVAL the input value of option_len is less than the size of the output option value EIO an internal error occurred
See also: setsockopt() (see section 6.2.4.5)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 55
6.2.4.5 setsockopt
Synopsis:
int setsockopt(int sock, int level, int option_name, const void *option_value, socklen_t option_len)
Description: Set socket options. Set options of a socket. Parameter level defines protocol level. Two groups SOL_SOCKET and IPPROTO_IP are supported. Supported options for SOL_SOCKET are following. • SO_RCVBUF: If the value provided in the int object referenced by option_value is ANIS_RCVBUF_NO_LIMIT the limit of the sockets socket receive buffer is set to unlimited. Otherwise it is set to the given value in bytes, rounded up to a multiple of the MTU. If zero value is provided as input value no reception buffers are assigned to the socket. Each time packet is received the whole MTU size (one mbuf) is taken from the pool of assigned buffers. In case of setting the limit to lower value than the count of the currently occupied reception buffers, no buffer is released, and the limit is applied to all the new messages. • SO_REUSEADDR: Indicates that the rules used in validating addresses supplied in a bind() (see section 6.2.4.3) call should allow reuse of local addresses. For PF_INET sockets this means that a socket may always bind. Argument is an integer boolean flag. • SO_FLUSH_ARP: Flush ARP record for the given IP together with all the packets scheduled to send to the destination IP. Expected is struct in_addr value in the network order representing IP. If there is already ongoing write of the packet to the Ethernet driver to the destination IP, the packet is not dropped, but it is sent with the resolved MAC address from the time before ARP record flush. The SO_FLUSH_ARP option is an ANIS-specific addition to the socket API and may be disabled by a configuration option.
In case several sockets are being bind to the same IP:PORT, SO_REUSEADDR needs to be set latest before 2nd bind to the 2nd socket. If there are several sockets bound to the same IP:PORT pair, the unicast messages are delivered only to the one target socket, the first one bound. And if there are not enough buffers available due to reception buffer limit set, the message is discarded even there are other sockets with valid IP:PORT. In case of Multicast traffic the message is delivered to all the socket within the same group and with sufficient reception buffers. In case of the Broadcast traffic the message is delivered to all the sockets bound to the target segment IP:PORT and with sufficient reception buffers. Supported options for IPPROTO_IP are following.
• IP_ADD_MEMBERSHIP: Join a multicast group. Argument is an ip_mreq structure. Local interface IP or IN- ADDR_ANY can be provided as interface address. If INADDR_ANY is used 1st configured interface in the system is used as outgoing device. This can be later changed by the IP_MULTICAST_IF option. Each unique group can be added just once to the socket. • IP_DROP_MEMBERSHIP: Leave a multicast group. Argument is an ip_mreq structure, where member "imr_interface" is ignored. • IP_MULTICAST_TTL: Set the time-to-live value of outgoing multicast packets for this socket. It is very important for multicast packets to set the smallest TTL possible. The default is 1 which means that multicast packets don’t leave the local network unless the user program explicitly requests it. Argument is an integer. • IP_MULTICAST_IF: Set the local device for a multicast socket. Argument is an ip_mreq structure, the same one as for IP_ADD_MEMBERSHIP. Only member ’imr_interface’ needs to be specified, other members are ignored. • IP_MULTICAST_LOOP: Set a boolean integer argument that determines whether sent multicast packets should be looped back to the local sockets. Multicast loop is enabled by default on newly created sockets. Example:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
56 ANIS POSIX API Reference
sockA (MC loop false, group X), SockB (MC loop true, group X) > sendto(sockA) > Message is not received by any
socket.
sockA(MC loop false, group X), SockB (MC loop true, group X) > sendto(sockB) > Messages is received back by sockB
and SockA sockets.
Upon success 0 is returned. If an error occurred the function returns -1 and sets errno.
Pre-Conditions: The ANIS API must have been initialized successfully using anis_init() (see section 6.2.4.1).
Parameters: sock [IN] the socket descriptor whose options shall be set level [IN] the protocol level option_name [IN] which option to set option_value [IN] the new value of the option option_len [IN] size of the buffer passed in option_value
Returns: On success, the function returns 0. EOPNOTSUPP level is not SOL_SOCKET nor IPPROTO_IP ENOPROTOOPT option_name is none of supported ones EINVAL option_len is not equal to the size of bytes of the object referenced by option_value. Or the provided input values are out of allowed input range. Or socket is already member of the provided group. Or there is no space for more groups to be added. Or there is no ARP record for given IP to FLUSH. Or the ARP table is static. EPERM SO_FLUSH_ARP is not allowed by the configuration. EBADF sock is not a valid socket descriptor EIO an internal error occurred
See also: getsockopt() (see section 6.2.4.4)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 57
6.2.4.6 getsockname
Synopsis:
int getsockname(int sock, struct sockaddr *address, socklen_t *address_len)
Description: Retrieve local address of socket. Retrieve the local address the socket sock is bound to and store it in address. The parameter address_len must contain the length of the buffer provided in address when this function is called. If the given socket is bound, getsockname() (see section 6.2.4.6) will set address_len to the amount of bytes written into address. If the given socket is not bound, getsockname() (see section 6.2.4.6) will set address_len to zero. Upon success 0 is returned. If an error occurred the function returns -1 and sets errno.
Pre-Conditions: The ANIS API must have been initialized successfully using anis_init() (see section 6.2.4.1).
Parameters: sock [IN] the socket descriptor whose local address shall be retrieved address [OUT] the local address of the socket sock address_len [INOUT] the length of the buffer provided in address when called; the length of the address upon return (if bound) or 0 (if not bound)
Returns: On success, the function returns 0. EINVAL address_len is less than the size, in bytes, of a struct sockaddr_in. EBADF sock is not a valid socket descriptor EIO an internal error occurred
See also: bind() (see section 6.2.4.3)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
58 ANIS POSIX API Reference
6.2.4.7 recvfrom
Synopsis:
ssize_t recvfrom(int sock, void *buffer, size_t length, int flags, struct sockaddr *address, socklen_t *address_len)
Description: Retrieve a message from a socket. Dequeue the oldest message from the sockets sock message queue and return its first N bytes in buffer, where N is the lesser of the value provided in length and the message size. If the message queue is currently empty and the MSG_DONTWAIT flag is not set in flags, recvfrom() (see section 6.2.4.7) blocks until a message is received or an error occurs. If the message queue is currently empty and the MSG_DONTWAIT flag is set in flags, recvfrom() (see section 6.2.4.7) returns immediately with error EAGAIN. If the output parameter address is not NULL, the source address of the received message is returned in this buffer and address_len is set to the length of the value written into address. If the application does not need the source address of the message, it may set address and address_len to NULL.
Pre-Conditions: The ANIS API must have been initialized successfully using anis_init() (see section 6.2.4.1).
Parameters: sock [IN] the socket descriptor to be read from buffer [OUT] the output buffer used to store the received message length [IN] the size of the buffer provided in buffer flags [IN] receive semantics; either zero or MSG_DONTWAIT address [OUT] the output buffer used to store the source address of the received message address_len [INOUT] the length of the buffer provided in address when called; the length of the address upon return
Returns: If a message was successfully received that did fit into the provided buffer, recvfrom() (see section 6.2.4.7) returns the size of the message in bytes. If the message did not fit completely into the buffer, recvfrom() (see section 6.2.4.7) returns -1 and sets errno to EMSGSIZE. In this case only the first length bytes are available to the caller. If an error occurred, recvfrom() (see section 6.2.4.7) returns -1 and sets errno. EINVAL address_len is less than the size, in bytes, of a struct sockaddr_in EINVAL unsupported flags are set in flags ERANGE length is greater than the maximum message size of 65507 bytes EPERM sock is not bound EAGAIN the message queue of sock is empty and the MSG_DONTWAIT flag is set in flags EINTR a signal is received while blocking EBADF sock is closed whilst blocking EBADF sock is not a valid socket descriptor EIO an internal error occurred
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 59
6.2.4.8 sendto
Synopsis:
ssize_t sendto(int sock, const void *message, size_t length, int flags, const struct sockaddr *dest_addr, socklen_t dest_len)
Description: Send a message. The function sendto() (see section 6.2.4.8) sends the message of length length given in message using the socket sock to the destination dest_addr. If the peer address address is the limited broadcast address (i.e. 255.255.255.255), the message is send to the directed broadcast address of the local network the socket is bound to. If the sending socket is bound to INADDR_ANY the outgoing device is selected by the ANIS. In case of multicast message the outgoing interface can be set via IP_MULTICAST_IF, or the interface is selected based on the group membership registration via IP_ADD_MEMBERSHIP. If none of above succeeds the message is sent out via 1st configured interface. If ANIS does not have sufficient resources to send the message and the MSG_DONTWAIT flag is not set in flags, the sendto() (see section 6.2.4.8) function will block until resources become available. If the flag is set, the function returns immediately in this case with an error.
Pre-Conditions: The ANIS API must have been initialized successfully using anis_init() (see section 6.2.4.1).
Parameters: sock [IN] the socket descriptor to be used for sending message [IN] the buffer used to store the message to be send length [IN] the size of the message stored in message flags [IN] send semantics; either zero or MSG_DONTWAIT dest_addr [IN] the destination address of the message dest_len [IN] the length in bytes of the dest_addr buffer
Returns: If a message was successfully send, sendto() (see section 6.2.4.8) returns the number of bytes send. If an error occurred sendto() (see section 6.2.4.8) returns -1 and sets errno. EPERM sock is not bound EINVAL dest_len is not equal to the size, in bytes, of a struct sockaddr_in EMSGSIZE length is greater than the maximum message size of 65507 bytes EAGAIN ANIS does not have sufficient resource to send the message and the MSG_DONTWAIT flag is set in flags EINVAL unsupported flags are set in flags EINTR a signal is received while blocking EBADF sock is closed whilst blocking EBADF sock is not a valid socket descriptor EIO an internal error occurred
Note: The application should specify the peer address in a struct sockaddr_in object, whose address is cast to a (struct sockaddr *) when passed to sendto() (see section 6.2.4.8).
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
60 ANIS POSIX API Reference
6.2.4.9 select
Synopsis:
int select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
Description: Wait for an event to occur on a set of sockets. The select() (see section 6.2.4.9) function operates on three sets of sockets. The "read set", whose address is given in the readfds argument, the "write set" whose address is given in the writefds argument, and the "exception set" whose address is given in the exceptfds set. Sockets are added to these sets using the macro FD_SET() (see section 6.2.2). The number of the socket descriptor with the largest value, incremented by one, must be passed to select() (see section 6.2.4.9) in the nfds argument. In the timeout argument the application may specify the maximal blocking time. If no timeout is specified it is indefinite. If called the select() (see section 6.2.4.9) function blocks until either at least one of the sockets in the input sets becomes ready or the timeout expires. Then the sets are modified to contain only the socket descriptors that became ready. In the case of a timeout the sets are set to empty. The application can test if a certain socket became ready using the FD_ISSET() (see section 6.2.2) macro. The following rules are used to decide if a socket is ready: • A socket in the readfds set is ready if recvfrom() (see section 6.2.4.7) with the MSG_DONTWAIT flag clear would return successfully. • A socket in the writefds set is ready if sendto() (see section 6.2.4.8) with the MSG_DONTWAIT flag clear would return successfully. • A socket in the errorfds set is never ready.
Parameters: nfds [IN] range of socket descriptors to be tested readfds [INOUT] set of socket descriptors for receiving writefds [INOUT] set of socket descriptors for sending exceptfds [INOUT] set of socket descriptors for exceptions timeout [IN] timeout for the select operation
Returns: The total number of socket descriptors in all three output sets that are returned. In case of timeout this number is zero. If an error occurred -1 is returned and errno is set. EBADF at least one of the sockets in the sets is not a valid socket descriptor EINVAL nfds is not in the range 0 to FD_SETSIZE EINTR a signal was received while blocking EPERM sock is not bound EINVAL timeout is not a valid timeout value (i.e. the microsecond value is not in the range 0 to 999999) EBADF one of the sockets in the input sets is closed whilst blocking EIO an internal error occurred
Note: There are select() (see section 6.2.4.9) implementations that update timeout to indicate how much time of the timeout was left when the function returned. This select() (see section 6.2.4.9) implementation does not update the timeout argument.
Warning:
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisSocket 61
Even if a socket is returned as ready, a sendto() (see section 6.2.4.8) or recvfrom() (see section 6.2.4.7) on it with the MSG_DONTWAIT flag not set, might still block. E.g. maybe another thread did read the message or exhausted ANIS resources. Or the message received on the socket had an invalid checksum and was discarded by recvfrom() (see section 6.2.4.7). So an application should always use MSG_DONTWAIT if it want to be sure that these functions do not block.
See also: FD_SET() (see section 6.2.2), FD_ISSET() (see section 6.2.2), recvfrom() (see section 6.2.4.7), sendto() (see section 6.2.4.8)
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
62 ANIS POSIX API Reference
6.3 AnisInstr
6.3.1 Structure Definitions
6.3.1.1 struct anis_instr_intf_stat_s
ANIS interface specific instrumentation API structure. This data structure is used to communicate network interface statistics to an application.
Synopsis:
struct anis_instr_intf_stat_s { uint32_t intf_enabled; uint32_t intf_ip_address; uint32_t intf_netmask; uint8_t intf_mac_address[6]; uint32_t intf_link_status; uint32_t intf_link_speed; uint32_t instr_fragTimeout; uint32_t instr_fragSpace; uint32_t instr_fragError; uint32_t instr_fragOffset; uint32_t instr_sockRecvBuf; uint32_t instr_icmpType; uint32_t instr_icmpFrag; uint32_t instr_icmpSum; uint32_t instr_igmpType; uint32_t instr_igmpFrag; uint32_t instr_igmpSum; uint32_t instr_ipSum; uint32_t instr_ipHeaderConstant; uint32_t instr_ipSize; uint32_t instr_ipProtocol; uint32_t instr_noSocket; uint32_t instr_badIP; uint32_t instr_hostUnreach; uint32_t instr_arpProtocol; uint32_t instr_txDrop; };
Structure Element Description: intf_enabled Status of the interface configuration Indication of the interface configuration status. If the interface is configured then 1 is stored in the variable. Otherwise 0. intf_ip_address The configured IP address of the interface. The IP address is stored in the network byte order. intf_netmask The configured network mask of the interface. The IP address is stored in the network byte order. intf_mac_address The MAC address of the interface. The field is set to zero for local loopback interface. intf_link_status Current interface link status. Indication of the interface link status from the underlying ethernet driver. The value 0 indicates link down, the value 1 link up. This member is set to 0 for the localhost loopback interface. intf_link_speed Current interface link speed.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisInstr 63
Indication of the interface link speed from the underlying ethernet driver in megabits per second. This member is
set to 0 for the localhost loopback interface.
instr_fragTimeout The number of FRAG_TIMEOUT class errors.
It is incremented if the fragmentation timeout between reception of two consecutive fragments belonging to the
same IP datagram is exceeded.
instr_fragSpace The number of FRAG_SPACE class errors.
It is incremented if the maximum number of concurrent fragmented IP datagrams supported is exceeded.
instr_fragError The number of FRAG_ERROR class errors.
It is incremented if fragments are received out of order and either no previous fragment of the datagram was
received or the previous received fragments were dropped due to other constraints (e.g. time out).
instr_fragOffset The number of FRAG_OFFSET class errors.
It is incremented if fragments are received out of order and at least one previous fragment was received.
instr_sockRecvBuf The number of SOCK_RECVBUF class errors.
It is incremented if a IP datagram is received which would cause the destination socket to exceed its receive buffer
size limit.
instr_icmpType The number of ICMP_TYPE class errors.
It is incremented if an ICMP datagram is received with invalid or unsupported values in the ICMP "Type" or "Code"
header fields.
instr_icmpFrag The number of ICMP_FRAG class errors.
It is incremented if an ICMP datagram is received with the fragmentation bit set in the IP header.
instr_icmpSum The number of ICMP_CHKSUM class errors.
It is incremented if an ICMP datagram with invalid checksum is received.
instr_igmpType The number of IGMP_TYPE class errors.
It is incremented if an IGMP datagram is received with invalid or unsupported values in the IGMP "Type" header
field.
instr_igmpFrag The number of IGMP_FRAG class errors.
It is incremented if an IGMP datagram is received with the fragmentation bit set in the IP header.
instr_igmpSum The number of IGMP_CHKSUM class errors.
It is incremented if an IGMP datagram with invalid checksum is received.
instr_ipSum The number of IP_CHKSUM class errors.
It is incremented if an IP datagram with invalid checksum is received.
instr_ipHeaderConstant The number of IP_HDR class errors.
It is incremented if an IP datagram with invalid or unsupported values in the header (except those covered by
IP_SIZE and IP_PROTO) is received.
instr_ipSize The number of IP_SIZE class errors.
It is incremented if an IP datagram with an invalid value in the "Total Length" header field is received.
instr_ipProtocol The number of IP_PROTO class errors.
It is incremented if an IP datagram with invalid or unsupported value in the IP header "Protocol" field is received.
instr_noSocket The number of NO_SOCK class errors.
It is incremented if a UDP datagram is received, but no socket is bound to the destination address.
instr_badIP The number of BAD_IP class errors.
It is incremented if an IP datagram is received, but the destination address does match neither the configured
address nor the broadcast address. It is also incremented if the source address is a broadcast address, multicast
address or a local loopback address.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
64 ANIS POSIX API Reference
instr_hostUnreach The number of HOST_UNREACHABLE class errors
It is incremented if the application tried to send data to a host, which is not reachable.
instr_arpProtocol The number of ARP_PROTO class errors
It is incremented if the ANISFP stack receives ARP packet with unexpected content in the ARP header.
instr_txDrop The number of TX_DROP class errors
It is incremented if the ethernet driver reports an error in transmit (vm_write()) operation. This counter is not used
if the txErrorFatal configuration property is true.
Associated Data Type
anis_instr_intf_stat_t ANIS interface specific instrumentation API structure.
6.3.1.2 struct anis_instr_stat_s
ANIS instrumentation API data structure. This data structure is used to communicate network interface statistics to an application.
Synopsis: struct anis_instr_stat_s { uint32_t instr_sendNoSrc; uint32_t instr_udpLength; uint32_t instr_udpSum; uint32_t instr_socketList; anis_instr_intf_stat_t intf[ANIS_ALL_INTF]; };
Structure Element Description: instr_sendNoSrc The number of SEND_NOSRC class errors. It is incremented if the application tried to send on an unbound socket. instr_udpLength The number of UDP_LENGTH class errors It is incremented if a UDP datagram is reassembled and some data left in the buffer for reassembly. instr_udpSum The number of UDP_CHKSUM class errors It is incremented if a UDP datagram with invalid checksum is received. In the certified ANIS variant this is only checked for UDP datagrams that are fragmented at the IP level. instr_socketList The number of SOCKET_LIST class errors. ANIS reserves internal memory to store association between multicast packets and receiving sockets. If a packet is not delivered to a socket because ANIS ran out of memory, this counter is incremented. intf Interface specific counters Field of anis_instr_intf_stat_t structures to access interface specific counters.
Associated Data Type
anis_instr_stat_t ANIS instrumentation API data structure.
6.3.2 Defines
ANIS_ALL_INTF
Maximum number of Ethernet interfaces including localhost loopback.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisInstr 65
6.3.3 Data Type Definitions
anis_instr_e_t ANIS instrumentation API service return codes.
anis_instr_intf_stat_t ANIS interface specific instrumentation API structure.
This data structure is used to communicate network interface statistics to an application.
anis_instr_stat_t ANIS instrumentation API data structure.
This data structure is used to communicate network interface statistics to an application.
anis_instr_t ANIS instrumentation API handle.
This data type is used in the ANIS instrumentation API for handles that identify the open instance of the instru-
mentation channel.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
66 ANIS POSIX API Reference
6.3.4 Enumerations
Enumeration type anis_instr_e
ANIS instrumentation API service return codes.
Name Description
ANIS_INSTR_E_OK The instrumentation API call was successful.
ANIS_INSTR_E_INVAL The instrumentation API call failed due to invalid arguments.
ANIS_INSTR_E_PERM The instrumentation API call failed due to insufficient access rights.
ANIS_INSTR_E_NO_MEM The instrumentation API call failed due to missing resources.
ANIS_INSTR_E_NO_ENT The instrumentation API call failed as the given ANIS instance does not exist.
ANIS_INSTR_E_SYS The instrumentation API call failed due to an internal error.
ANIS_INSTR_E_BUSY The instrumentation read channel is already open.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisInstr 67
6.3.5 Functions
6.3.5.1 anis_instr_open
Synopsis:
anis_instr_e_t anis_instr_open(const char *name, anis_instr_t *handle)
Description: Open instrumentation connection. This function opens an instrumentation connection on an ANIS instance, specified by parameter name.
Parameters: name [IN] Name of ANIS instance. handle [OUT] Handle to ANIS instance.
Returns: On success, the function returns ANIS_INSTR_E_OK and a valid handle in parameter handle. ANIS_INSTR_E_NO_ENT No ANIS instance with the specified name exists. ANIS_INSTR_E_NO_PERM The caller does not have sufficient rights to access the instrumentation statistics. ANIS_INSTR_E_NO_MEM The caller does not have sufficient resources to establish a connection with the ANIS instance. ANIS_INSTR_E_INVAL The length of name exceeds ANIS_MAX_NAMELEN. ANIS_INSTR_E_SYS The connection with the ANIS instance failed due to internal reasons.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
68 ANIS POSIX API Reference
6.3.5.2 anis_instr_close
Synopsis:
anis_instr_e_t anis_instr_close(anis_instr_t *handle)
Description: Close instrumentation connection. This function closes the instrumentation connection with the ANIS instance referenced by parameter handle.
Parameters: handle [IN] Handle to ANIS instance.
Returns: On success, the function returns ANIS_INSTR_E_OK. ANIS_INSTR_E_INVAL handle is not a valid ANIS instrumentation handle. ANIS_INSTR_E_SYS The connection with the ANIS instance fails.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisInstr 69
6.3.5.3 anis_instr_read
Synopsis:
anis_instr_e_t anis_instr_read(anis_instr_t *handle, anis_instr_stat_t *stats)
Description: Read instrumentation data. This function retrieves instrumentation statistics from the ANIS instance referenced by parameter handle. It returns statistics for all the interfaces including localhost loopback. Valid records are indicated by the value ’1’ in the intf_enabled member. The order of the counters is the same as order of configured interfaces in the system. Localhost loopback is all the time the last one from the group of enabled interfaces. Example of "intf_enabled" values based on the configured interfaces: Enabled interfaces (1)+ localhost loopback: 1 1 0 0 0 0 0 0 Enabled interfaces (3)+ localhost loopback: 1 1 1 1 0 0 0 0 Enabled interfaces (7)+ localhost loopback: 1 1 1 1 1 1 1 1
Parameters: handle [IN] Handle to ANIS instance. stats [OUT] Pointer to structure to receive the statistics.
Returns: On success, the function returns ANIS_INSTR_E_OK. ANIS_INSTR_E_INVAL handle is not a valid ANIS instrumentation handle. ANIS_INSTR_E_SYS The connection with the ANIS instance fails.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
7 ANIS Startup Configuration API Reference
This section presents the data types that define ANIS startup configuration file format.
7.1 Configuration Properties
The following properties can be specified in the startup configuration:
Property Name Value Union Member Description arpTableSize p_uint32 ARP table size arpQueue p_uint32 ARP queue length limit arpResolvTimeout p_uint32 ARP resolution timeout flushEnable p_bool enable SO_FLUSH_ARP feature diagnosticMessages p_uint32 enable diagnostic messages mtu p_uint32 network MTU numBuffers p_uint32 number of network buffers numSockets p_uint32 number of sockets numInterfaces p_uint32 number of network interfaces peerSize p_uint32 number of entries in the peer cache staticConf p_bool enable static ARP configuration txErrorFatal p_bool enable HM error if ethernet driver fails arp//enable p_bool enabled/disabled state of the ARP record arp//ip p_ip_address IP address of the ARP record arp//mac p_mac_address MAC address of the ARP record /ip p_ip_address network interface IP address /mc_level p_uint32 multicast support level /netmask p_ip_address network interface network mask /provider p_string pathname of the file provider implementing the interface /ttl p_uint32 network interface TTL /gateway p_ip_address network interface gateway address
7.2 AnisStartupConfig
7.2.1 Structure Definitions
7.2.1.1 struct anis_config_header_s
Configuration header.
Synopsis:
struct anis_config_header_s { uint32_t magic; uint32_t num_properties; };
Structure Element Description: magic identifier equal to ANISFP_CONFIG_HEADER_MAGIC
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
AnisStartupConfig 71
num_properties number of anisfp_property_t structures following the header
Associated Data Type
anis_config_header_t Configuration header.
7.2.1.2 union anis_config_value_u
Configuration property value.
Synopsis:
union anis_config_value_u { uint32_t p_uint32; uint32_t p_bool; unsigned char p_ip_address[4]; unsigned char p_mac_address[6]; char p_string[256]; };
Union Element Description: p_uint32 integer value p_bool boolean value (1 = true, 0 = false) p_ip_address IP address in network byte order p_mac_address MAC address p_string PikeOS filesystem path
Associated Data Type
anis_config_value_t Configuration property value.
7.2.1.3 struct anis_config_property_s
Configuration property.
Synopsis:
struct anis_config_property_s { char name[64]; anis_config_value_t value; };
Structure Element Description: name property name value property value
Associated Data Type
anis_config_property_t Configuration property.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.
72 ANIS Startup Configuration API Reference
7.2.2 Defines
ANIS_CONFIG_HEADER_MAGIC
Configuration header magic value.
Description:
Arbitrary number.
7.2.3 Data Type Definitions
anis_config_header_t Configuration header.
anis_config_value_t Configuration property value.
anis_config_property_t Configuration property.
c Copyright 2005 – 2019 SYSGO GmbH, all rights reserved.