Author: Exoligent’s Team
Description: The document's description

# POWERFIP Library : User’s Guide

Exoligent’s Team
info@exoligent.com
version v1.5.0, 2026-03-09

## 1. Disclaimer

Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. EXOLIGENT MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Exoligent disclaims all liability arising from this information and its use. Use of Exoligent devices in life support and/or safety applications is entirely at the buyer’s risk, and the buyer agrees to defend, indemnify and hold harmless Exoligent from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Exoligent intellectual property rights unless otherwise stated.

Exoligent SARL
390 rue d’Estienne d’Orves, 92700 Colombes - France
Tel: +33(0) 1 42 42 42 00
Web Site: https://www.exoligent.com/
Copyright © 2022 Exoligent SARL. All rights reserved.

## 2. Introduction

PowerFIP library is a C API providing a programming interface to the Exoligent’s FIP/WorldFIP coprocessor.
It offers a set of functions for the FIP/WorldFIP network control:

- Create/Delete FIP objects

  - Node

    - Bus Arbiter macrocycle(s)

    - AE/LE(s) (Application/Layer Entity)

      - MPS variable(s)

      - SM-MPS variable(s)

- Conduct FIP Exchanges:

  - Periodic MPS variables:
    Transfers, reads and writes buffers with ID_DAT/RP_DAT transactions

  - Aperiodic MPS variables:
    Process buffer transfer requests (RP_DAT_RQx, ID_RQx/RP_RQx)

  - Periodic messaging:
    Exchanges messages with ID_MSG/RP_MSG_X using periodic channels.

  - Aperiodic messaging:
    Processes messages sent via aperiodic channel.
    Requests are made to bus arbiter using RP_DAT_MSG frames.

- Bus arbiter capability:

  - Start/Stop/Commute macrocycle(s)

- Medium Redundancy

  - Channels control and status

- Attach user callbacks to process FIP events

  - on RP_DAT rx/tx frames

  - on RP_MSG_X rx/tx frames

  - on ID_DAT rx/tx frames [pure event]

  - on RP_RQx tx frames [aperiodic requests]

  - on Bus Arbiter’s change of state

PowerFIP overview (Principle Diagram)

## 3. Installation

Let’s start by downloading the archive of the latest version of the library from the Exoligent website: Download section

### 3.1. Linux

The linux archive has the following tree structure

  - [docs]

    - PowerFIP Library - User’s Guide (*.pdf) :
      The User’s Guide in PDF format.

    - powerfip.html :
      The User’s Guide in HTML format.

  - [drivers]

    - [linux]
      The source code of the Linux kernel module for Exoligent PowerFIP PCI/PCIe devices:

      - [udev.rules.d]

        - 10-powerfip.rules

      - install.sh

      - Makefile

      - powerfip-pci.c

      - powerfip-pci.h

      - uninstall.sh

  - [firmware]
    The PowerFIP coprocessor firmware for RISC-V Soft-CPU target :

    - powerfip-firmware.bin

  - [include]
    Header files to include in your projects to use the library:

    - libpowerfip.h

    - mbox-common.h

    - powerfip-common.h

    - powerfip-drv.h

    - powerfip-mbox-common.h

  - [lib]

    - [aarch64]

      - [static]

        - libpowerfip.a [aarch64 static lib]

      - libpowerfip.so.1.5.0 [aarch64 shared lib]

    - [arm]

      - [static]

        - libpowerfip.a [arm static lib]

      - libpowerfip.so.1.5.0 [arm shared lib]

    - [i386]

      - [static]

        - libpowerfip.a [x86 static lib]

      - libpowerfip.so.1.5.0 [x86 shared lib]

    - [x86_64]

      - [static]

        - libpowerfip.a [x86_64 static lib]

      - libpowerfip.so.1.5.0 [x86_64 shared lib]

  - [tools] :
    Turnkey examples to get started as soon as possible!

    - [pwrfip_2sta]

    - [pwrfip_nsta]

    - [pwrfip_perf_long_frm]

    - [pwrfip_performance]

    - [pwrfip_ping]

    - [mbfip_gateway]

    - [uafip_tsn_gateway]

  - install.sh

  - uninstall.sh

  - release-notes.txt

  - readme.txt

#### 3.1.1. Kernel Module

Open a terminal, and go to the linux driver directory:

    $ cd driver/linux

Execute the following commands to build and install the kernel module:

    $ make
    $ sudo ./install.sh

| Two files will be copied to your system `powerfip.ko` file to the path: /lib/modules/$(uname -r)/kernel/drivers/fip `10-powerfip.rules` file to the path: /etc/udev/rules.d

To remove the kernel module, enter the following command :

    $ sudo ./uninstall.sh

#### 3.1.2. Firmware/Library

Open a terminal, and go to the archive package root.
Then, enter the following command to install the PowerFIP firmware and library on your machine:

    $ sudo ./install.sh

| Files will be copied to your system `powerfip-firmware.bin` file to the path: /usr/local/lib/firmware `libpowerfip.a` and `libpowerfip.so.1.5.0` files to the path: /usr/local/lib `header (*.h)` files to the path: /usr/local/include/powerfip

To remove these files, enter the following command:

    $ sudo ./uninstall.sh

### 3.2. Windows

Run the lastest installer (.exe), and follow the wizard steps. All the files will be copied to the folder:

    C:\Program Files (x86)\Exoligent\PowerFIP\

This directory has the following tree structure

  - [docs]

    - PowerFIP Library - User’s Guide (*.pdf) :
      The User’s Guide in PDF format.

    - powerfip.html :
      The User’s Guide in HTML format.

  - [drivers]

    - [win]
      The binaries of the Windows driver for Exoligent PowerFIP PCI/PCIe devices:

      - [Driver]

        - [x86]

          - pwrfip.sys

        - [x86-64]

          - pwrfip64.sys

      - pwrfip.cat

      - pwrfip.inf

      - pwrfip64.cat

  - [firmware]
    The PowerFIP coprocessor firmware for RISC-V Soft-CPU target :

    - powerfip-firmware.bin

  - [include]
    Header files to include in your projects to use the library:

    - libpowerfip.h

    - mbox-common.h

    - powerfip-common.h

    - powerfip-drv.h

    - powerfip-mbox-common.h

  - [lib]

    - [i686]

      - [static] - MinGW compiler: i686-8.1.0-posix-dwarf-rt_v6-rev0

        - libpowerfip.a [x86 static lib]

      - libpowerfip.dll [x86 shared lib]

      - libpowerfip.lib [x86 import lib]

    - [x86_64]

      - [static] - MinGW compiler: x86_64-8.1.0-posix-seh-rt_v6-rev0

        - libpowerfip.a [x86_64 static lib]

      - libpowerfip.dll [x86_64 shared lib]

      - libpowerfip.lib [x86_64 import lib]

  - [tools] :
    Turnkey examples to get started as soon as possible!

    - [pwrfip_2sta]

    - [pwrfip_nsta]

    - [pwrfip_perf_long_frm]

    - [pwrfip_performance]

    - [pwrfip_ping]

  - release-notes.txt

  - readme.txt

#### 3.2.1. Driver

Installation

  - Open the Device Manager window

    - Press Windows+X or right-click to Start button, then a menu will appear

    - Select Device Manager from the list

  - Double-click on the new Other PCI bridge device detected

  - Click on Update the driver

  - Select the last package driver, and click on Next button

    # Target directory for driver
    C:\Program Files (x86)\Exoligent\PowerFIP\drivers\win

- PowerFIP driver is now installed !

  Uninstallation

- Go to the Device Manager window

- Right-click on the PowerFIP device to be removed, and click on Uninstall button

- Check Remove the driver for this device, and confirm the device uninstall

#### 3.2.2. Firmware/Library

The PowerFIP firmware and library will be automatically installed by the package wizard.

| Files will be copied to your system `powerfip-firmware.bin` file to the path: C:\Program Files (x86)\Exoligent\PowerFIP\firmware `libpowerfip.dll` file to the path: C:\Program Files (x86)\Exoligent\PowerFIP\lib `header (*.h)` files to the path: C:\Program Files (x86)\Exoligent\PowerFIP\include

To remove the package, execute the uninstaller wizard:

    C:\Program Files (x86)\Exoligent\PowerFIP\Uninstall.exe

### 3.3. Examples

To quickly get into the swing of things, the source code of some examples is provided with the package.

To access to the examples, open a terminal and enter the following commands:

Linux

    # From extracted archive directory
    $ cd tools

Windows

    $ cd C:\Program Files (x86)\Exoligent\PowerFIP\tools

| If you do not have administrator rights, it is advisable to copy/paste the following directories into your own workspace: C:\Program Files (x86)\Exoligent\PowerFIP\tools C:\Program Files (x86)\Exoligent\PowerFIP\lib C:\Program Files (x86)\Exoligent\PowerFIP\include For example paste it to a new directory in 'My Documents': C:\Users\%USERNAME%\Documents\PowerFIP\tools C:\Users\%USERNAME%\Documents\PowerFIP\lib C:\Users\%USERNAME%\Documents\PowerFIP\include

We will now briefly describe the examples:

#### 3.3.1. Simple Test - pwrfip_2sta

This example aims at making two FIP nodes communicate with each other through the FIP network with exchange of periodic and aperiodic variables.

The configuration of FIP nodes is done via static structures (see `tools/pwrfip_2sta/sta.h`), and tries to cover all available FIP services (MPS writing/reading, Aperiodic variable list requesting, Messages sending/receiving, SM-MPS reading, Presence Test, …​).

| The example will therefore only work completely if you have two PCI/PCIe PowerFIP devices connected together with a FIP cable. However, it is still possible to start a single station to observe the FIP traffic emitted by the device. Indeed the FIP node will try to start by default in master mode (with an active bus arbiter).

Build the example:

Linux

    $ cd tools/pwrfip_2sta

    # Build for i386 target (32-bit)
    $ make MACHINE=i386

    # Build for x86_64 target (64-bit)
    $ make MACHINE=x86_64

Windows

    # Build the example with static method way.
    $ set SYS_NAME=windows
    $ cd tools/pwrfip_2sta

    # Build for i686 target (32-bit)
    # Note: MinGW compiler: i686-8.1.0-posix-dwarf-rt_v6-rev0
    $ make MACHINE=i686

    # Build for x86_64 target (64-bit)
    # Note: MinGW compiler: x86_64-8.1.0-posix-seh-rt_v6-rev0
    $ make MACHINE=x86_64

Get the help:

Linux

    $ ./pwrfip_2sta -h

Windows

    $ pwrfip_2sta.exe -h

    Usage: pwrfip_2sta [OPTION]...

    It tests FIP board communication with PowerFIP library.
    By default, if no option is added, the app opens the first PCI/PCIe device
    with index 1 [-i 1], and starts FIP node 0 (addr=0) [-n 0] with bitrate sets
    to 1Mbps [-b 1].

    Options:
        -i   device index [default=1]
        -n   FIP node to start [default=0]
             0: node 0
             1: node 1
        -b   FIP bitrate [default=1]
             0: 31.25Kbps
             1: 1Mbps
             2: 2.5Mbps
             3: 5Mbps
             4: 12.5Mbps
             5: 25Mbps
        -r   FIP turn-around time in us [default=0]
             default TR times:
               @31.25Kbps: 424us
               @1Mbps    : 30us
               @2.5Mbps  : 30us
               @5Mbps    : 32us
               @12.5Mbps : 32us
               @25Mbps   : 32us
        -s   FIP silence time in us [default=0]
             default TS times:
               @31.25Kbps: 4096us
               @1Mbps    : 150us
               @2.5Mbps  : 96us
               @5Mbps    : 92us
               @12.5Mbps : 92us
               @25Mbps   : 92us
        -l   list the FIP boards present on the host machine
        -h   show this help and exit
        -v   show version and exit

    Examples:
        pwrfip_2sta -i 1 -n 0 -b 1 -r 30 -s 150

Launch FIP node 0:

Linux

    # Adding the SYS_NICE capapibity as Effective and Permitted to the binary
    # => This root command is executed only once after the binary building
    $ sudo setcap cap_sys_nice+ep ./pwrfip_2sta

    $ ./pwrfip_2sta -i 1 -n 0 -b 1

Windows

    $ pwrfip_2sta.exe -i 1 -n 0 -b 1

    [01-24 10:17:44.201472] app  => [info]  [fip] device info
    [01-24 10:17:44.201546] app  => [info]     index        : 1
    [01-24 10:17:44.201578] app  => [info]     fsn          : 0x28d00484cf61
    [01-24 10:17:44.201601] app  => [info]     vid          : 0x11aa
    [01-24 10:17:44.201624] app  => [info]     did          : 0x1556
    [01-24 10:17:44.201645] app  => [info]     ssvid        : 0x11aa
    [01-24 10:17:44.201662] app  => [info]     ssdid        : 0x5811
    [01-24 10:17:44.201682] app  => [info]     bar_cnt      : 2
    [01-24 10:17:44.201705] app  => [info]     bar_bsz[0]   : 4096
    [01-24 10:17:44.201730] app  => [info]     bar_base[0]  : 0xa6000000
    [01-24 10:17:44.201747] app  => [info]     bar_bsz[1]   : 33554432
    [01-24 10:17:44.201767] app  => [info]     bar_base[1]  : 0xa4000000
    [01-24 10:17:44.201791] app  => [info]     irq_number   : 148
    [01-24 10:17:44.201811] app  => [info]     drv_version  : 1.4.0
    [01-24 10:17:44.201831] app  => [info]  test: v2.2.0 - pwrfip lib: v1.1.0
    [01-24 10:17:44.201851] sta0 => [info]  [fip] node configuration
    [01-24 10:17:44.201872] sta0 => [info]  [fip] bus arbiter infos
    [01-24 10:17:44.201890] sta0 => [info]     start        : 1306800us
    [01-24 10:17:44.201909] sta0 => [info]     election     : 77700us
    [01-24 10:17:44.201928] sta0 => [info]  [fip] node init
    [01-24 10:17:44.258360] sta0 => [event] reset component (powerfip)
    [...]

The example sequence is as follows:

- Open PCI/PCIe device (index 1)

- Load Configuration (fip node 0)

- Start the Bus Arbiter (start-up time: 1306800us, election time: 77700us)

- Infinite Loop

| During this loop, an interrupt is raised by the FIP coprocessor each time an ID_DAT(0x9003) is transmitted on the FIP network (i.e. at the macrocycle frequency: here T=40ms). This interrupt triggers the user handler linked to the SM-MPS BA synchronization variable (see: `tst_pwrfip_ba_sync_handler` function in the file: `tools/pwrfip_2sta/sta.c`). As this function is clocked on the macrocycle, we take the opportunity to perform some actions within it: Station 0: Produce 1 periodic variable on the network 0x3800 (with aperiodic var/msg request capabilities enabled) [ie. can produce a RP_DAT_RQx and RP_DAT_MSG frames] Consume 1 periodic variable from the network 0x3801 Request for a list of aperiodic variables (by switching between two lists after each request) 1st list ⇒ 2 IDs: 0x7800, 0x7801 2nd list ⇒ 4 IDs: 0x1000, 0x1001, 0x1100, 0x1101

- Break the loop on an user keyboard press

- Stop Bus Arbiter

- Unload Configuration

- Close PCI/PCIe device

#### 3.3.2. Performance Test - pwrfip_performance

This example is very similar in structure to the previous example.
However, here the goal of the test is to measure the performance of the user read/write operation of the FIP variables from/to the database embedded in the FIP coprocessor.
Thanks to this we can evaluate the min/avg/max access times to the coprocessor depending on the amount of useful data read or written.

At the end of the test, a diagnostic report is generated and gives the access times (minimum, average, maximum) according to the length of the FIP user data produced or consumed: `tools/pwrfip_performance/report_idx1.txt`.

| In the same way as for the previous test, to have a complete performance report, the two FIP nodes in the example must be connected to each other. Example of two PCI/PCIe PowerFIP devices on the same PC with two terminals: Linux - Test launch
    # Adding the SYS_NICE capapibity as Effective and Permitted to the binary
    # => This root command is executed only once after the binary building
    $ sudo setcap cap_sys_nice+ep ./pwrfip_performance
    # => Terminal 1
    # starts PCI/PCIe device index 1 with FIP node configuration 0
    $ ./pwrfip_performance -i 1 -n 0
    # => Terminal 2
    # start PCI/PCIe device index 2 with FIP node configuration 1
    $ ./pwrfip_performance -i 2 -n 1
Windows - Test launch
    # => Terminal 1
    # starts PCI/PCIe device index 1 with FIP node configuration 0
    $ pwrfip_performance.exe -i 1 -n 0
    # => Terminal 2
    # start PCI/PCIe device index 2 with FIP node configuration 1
    $ pwrfip_performance.exe -i 2 -n 1

This makes it possible to generate performance curves according to the execution context (PC architecture, real-time OS, etc.).

## 4. Functions

In this chapter, we will discover and describe the whole API (Application Programming Interface) of POWERFIP.

### 4.1. General

#### 4.1.1. init

Description

  Library internal initialization

Prototype

    int pwrfip_init()

Parameters

  - IN - None

  - OUT - None

Return Value

  If successful, `pwrfip_init()` returns 0.
  If unsuccessful, `pwrfip_init()` returns -1 and sets errno value.

Remarks

| This function must always be called before using any other function of the library.

#### 4.1.2. exit

Description

  Free all internal ressources used by the PowerFIP library

Prototype

    void pwrfip_exit()

Parameters

  - IN - None

  - OUT - None

Return Value

  NONE

Remarks

| This function must always be called at the end of the use of the library.

#### 4.1.3. version_get

Description

  Gets the software library version.

Prototype

    const struct pwrfip_version *pwrfip_version_get()

Parameters

  - IN - None

  - OUT - None

Return Value

  Pointer to a `struct pwrfip_version`.

Example

    int main(int argc, char *argv[])
    {
        const struct pwrfip_version *lib_version;

        pwrfip_init();

        /* pwrfip - get lib version */
        lib_version = pwrfip_version_get();

        printf("pwrfip lib: v%d.%d.%d [build date: %02d/%02d/%02d]\n",
            lib_version->info.major,
            lib_version->info.minor,
            lib_version->info.patch,
            lib_version->date.info.month,
            lib_version->date.info.day,
            lib_version->date.info.year);

        pwrfip_exit();

        return 0;
    }

#### 4.1.4. error_get

Description

  Gets the last error code.

Prototype

    int pwrfip_error_get()

Parameters

  - IN - None

  - OUT - None

Return Value

  The last error code.

Remarks

  See `enum pwrfip_error_code` to get the list of the specific library errors codes.

#### 4.1.5. strerror

Description

  Gets the error string specified by its error code.

| The library provides this error code via the lvalue: errno or via `pwrfip_error_get()` function.

Prototype

    const char *pwrfip_strerror(int err)

Parameters

  - IN

    - err:
      Error code.

  - OUT - None

Return Value

  Error in string format.

Remarks

  See `enum pwrfip_error_code` to get the list of the specific library errors codes.

### 4.2. Device

#### 4.2.1. device_list_get

Description

  Gets the list of PCI/PCIe powerfip devices present on the system.

| The PowerFIP driver supports up to 16 devices.

Prototype

    int pwrfip_device_list_get(struct pwrfip_dev_infos *dev_infos,
                    int *dev_cnt)

Parameters

  - IN - None

  - OUT

    - dev_infos:
      Information list of detected devices.
      See `struct pwrfip_dev_infos`.

    - dev_cnt:
      Count of detected devices.

Return Value

  If successful, `pwrfip_device_list_get()` returns 0.
  If unsuccessful, `pwrfip_device_list_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameter.

#### 4.2.2. device_open

Description

  Opens a PCI/PCIe powerfip device.

Prototype

    struct pwrfip_dev *pwrfip_device_open(uint8_t dev_id)

Parameters

  - IN

    - dev_id:
      Device index on the system.

  - OUT - None

Return Value

  If successful, `pwrfip_device_open()` returns a new `struct pwrfip_dev` pointer (opaque structure).
  If unsuccessful, `pwrfip_device_open()` returns NULL and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameter.

  - ENOMEM:
    Memory allocation error.

  - [..]:
    Other posix errors related to a file opening error

#### 4.2.3. device_reset

Description

  Resets PCI/PCIe PowerFIP device.

  - FIP Coprocessor reset

  - Logic interface reset (of carrier board)

Prototype

    int pwrfip_device_reset(struct pwrfip_dev *dev)

Parameters

  - IN

    - dev:
      Pointer to the device to reset.

  - OUT - None

Return Value

  If successful, `pwrfip_device_reset()` returns 0.
  If unsuccessful, `pwrfip_device_reset()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameter.

#### 4.2.4. device_close

Description

  Closes a PCI/PCIe powerfip device.

Prototype

    int pwrfip_device_close(struct pwrfip_dev *dev)

Parameters

  - IN

    - dev:
      Pointer to the device to close.

  - OUT - None

Return Value

  If successful, `pwrfip_device_close()` returns 0.
  If unsuccessful, `pwrfip_device_close()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid device pointer.

#### 4.2.5. device_infos_get

Description

  Gets information relative to the PCI/PCIe device.

Prototype

    int pwrfip_device_infos_get(struct pwrfip_dev *dev,
                    struct pwrfip_dev_infos *info)

Parameters

  - IN

    - dev:
      Pointer to the device to query.

  - OUT

    - info:
      Info structure.
      See `struct pwrfip_dev_infos`.

Return Value

  If successful, `pwrfip_device_infos_get()` returns 0.
  If unsuccessful, `pwrfip_device_infos_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameter.

#### 4.2.6. device_report_get

Description

  Gets various information about the PowerFIP board.

Prototype

    int pwrfip_device_report_get(struct pwrfip_dev *dev,
                    struct pwrfip_dev_report *report)

Parameters

  - IN

    - dev:
      Pointer to the device to query.

  - OUT

    - report:
      Device report.
      See `struct pwrfip_dev_report`.

Return Value

  If successful, `pwrfip_device_report_get()` returns 0.
  If unsuccessful, `pwrfip_device_report_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameter.

### 4.3. AE/LE

#### 4.3.1. aele_create

Description

  The function `pwrfip_aele_create()` creates an Application/Layer entity attached to a FIP node. This container will gather all the production/consumtions variables and messages related to the local application.

Prototype

    struct pwrfip_aele *pwrfip_aele_create(struct pwrfip_node *node);

Parameters

  - IN

    - node:
      Pointer to a `struct pwrfip_node`.

  - OUT - None

Return Value

  Pointer to a `struct pwrfip_aele` (opaque structure).

#### 4.3.2. aele_delete

Description

  The function `pwrfip_aele_delete()` deallocates a specific application/layer entity; and removes all items (variable, messages) attached to it.

Prototype

    int pwrfip_aele_delete(struct pwrfip_aele *aele)

Parameters

  - IN

    - aele:
      Application entity to delete.

  - OUT - None

Return Value

  If successful, `pwrfip_aele_delete()` returns 0.
  If unsuccessful, `pwrfip_aele_delete()` returns -1 and sets errno to one of the following values:

  - PWRFIP_ERR_AELE_NOT_STOP:
    AE/LE is currently running. Stop it before try to delete it.

#### 4.3.3. msg_create

Description

  Creates a FIP message inside an user’s application context.

Prototype

    struct pwrfip_msg *pwrfip_msg_create(
                    struct pwrfip_aele *aele, struct pwrfip_msg_cfg *cfg)

Parameters

  - IN

    - aele:
      Pointer to a user’s application context (AE/LE).

    - cfg:
      Pointer to a message’s configuration structure.
      See `struct pwrfip_msg_cfg`.

  - OUT - None

Return Value

  If successful, `pwrfip_msg_create()` returns a new `struct pwrfip_msg` pointer.
  If unsuccessful, `pwrfip_msg_create()` returns NULL and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - ENOMEM:
    Memory allocation error.

  - PWRFIP_ERR_AELE_NOT_STOP:
    AE/LE is currently running. Stop it before trying to create new objects.

  - PWRFIP_ERR_CFG_MSG_EXIST:
    Impossible to create this message. The AE/LE context already contains a message with the same header.

  - PWRFIP_ERR_NODE_MSG_CAP_NOT_SUPPORTED:
    The node doesn’t support the messaging service.
    See `.msg.enable` field of `struct pwrfip_node_cfg`.

  - PWRFIP_ERR_CFG_MSG_TYPE_UNKNOWN:
    Unknown message type.
    See `enum pwrfip_msg_type`.

  - PWRFIP_ERR_CFG_MSG_TX_CH_PER_UNKNOWN:
    Unknown periodic message TX channel.
    See `enum pwrfip_msg_tx_channel`.

  - PWRFIP_ERR_CFG_MSG_TX_CH_PER_NOID:
    No ID attached to the periodic TX channel.
    See `.msg.tx_per_fifo_id[]` field of `struct pwrfip_node_cfg`.

  - PWRFIP_ERR_CFG_MSG_TX_ACK_MODE_UNKNOWN:
    Unknown message acknowledgement mode.
    See `enum pwrfip_msg_tx_ack_mode`.

Example

    static struct pwrfip_msg_cfg prod_msg_cfg = {
        .type = PWRFIP_MSG_TYPE_SEND,
        .tx.channel = PWRFIP_MSG_TX_CH_APER,
        .tx.ack_mode = PWRFIP_MSG_TX_ACK_MODE_SDA,
        /* local data link layer address: 0x0C0000 */
        .hdr.src.seg = 0,
        .hdr.src.lsap = 0x0C00, /* ssap */
        /* remote data link layer address: 0x0C0100 */
        .hdr.dst.seg = 0,
        .hdr.dst.lsap = 0x0C01, /* dsap (=target) */
        .pwrfip_msg_handler = NULL,
    };

    static struct pwrfip_msg_cfg cons_msg_cfg = {
        .type = PWRFIP_MSG_TYPE_RECV,
        /* remote data link layer address: 0x0C0100 */
        .hdr.src.seg = 0,
        .hdr.src.lsap = 0x0C01, /* ssap */
        /* local data link layer address: 0x0C0000 */
        .hdr.dst.seg = 0,
        .hdr.dst.lsap = 0x0C00, /* dsap (=target) */
        .pwrfip_msg_handler = NULL,
    };

    int main(int argc, char *argv[])
    {
        int i, err = 0;
        struct pwrfip_node_cfg node_cfg;
        struct pwrfip_node *node;
        struct pwrfip_aele *al;
        struct pwrfip_msg *prod_msg, *cons_msg;

        /**
         * Node initialization
         */
        memset(&node_cfg, 0, sizeof(struct pwrfip_node_cfg));
        node_cfg.fip_phy_addr = 0;
        node_cfg.fip_seg_num = 0;
        node_cfg.msg.enable = 1;
        if (node_cfg.msg.enable) {
            /* set rx messaging sensitivity only for messages destined
             * for segment 0 with DSAP values configured for the node
             */
            node_cfg.msg.rx_segment_tab[0] = PWRFIP_MSG_SEG_ACCEPT_LTD;
            node_cfg.msg.rx_fifo_size = 0; /* 0 to set default value (30) */
            node_cfg.msg.tx_aper_fifo_size = 0; /* default value for tx aper channel:
                                                 * tx fifo depth = 24 messages
                                                 */
            node_cfg.msg.tx_max_repeat = 3; /* 3 tx retries in case of error */
            /* periodic messaging channels are disabled */
            for (i = 0; i < PWRFIP_MSG_TX_CH_PER_CNT; ++i)
                node_cfg.msg.tx_per_fifo_id[i] = 0; /* no id attached */

        }
        /*...: other node configuration fields to fill (ba, handlers...) */
        node = pwrfip_node_init(&node_cfg);
        if (!node) {
            printf("node creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create an aele context */
        al = pwrfip_aele_create(node);
        if (!al) {
            printf("aele creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create a tx message */
        prod_msg = pwrfip_msg_create(al, &prod_msg_cfg);
        if (!prod_msg) {
            printf("tx message creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create a rx message */
        cons_msg = pwrfip_msg_create(al, &cons_msg_cfg);
        if (!cons_msg) {
            printf("rx message creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /**
         * Other tasks
         */
        /* ... */

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.3.4. msg_delete

Description

  Deallocates a specific message from an application entity (AE/LE).

Prototype

    int pwrfip_msg_delete(struct pwrfip_msg *msg)

Parameters

  - IN

    - msg:
      Pointer to the message to delete.
      See `struct pwrfip_msg`.

  - OUT - None

Return Value

  If successful, `pwrfip_msg_delete()` returns 0.
  If unsuccessful, `pwrfip_msg_delete()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameter.

  - PWRFIP_ERR_AELE_NOT_STOP:
    AE/LE attached to this message is currently running. Stop it before try to delete it.

#### 4.3.5. sm_var_create

Description

  Creates an additionnal SM-MPS variables inside an user’s application context.
  This function is used to allow the local node to consume SM-MPS variables produced by remote nodes.

Prototype

    struct pwrfip_var *pwrfip_sm_var_create(
                    struct pwrfip_aele *aele, enum pwrfip_sm_var_type type,
                    uint8_t node_addr)

Parameters

  - IN

    - aele:
      Pointer to a user’s application context (AE/LE).

    - type:
      Type of SM-MPS variable to create.
      See `enum pwrfip_sm_var_type`.

    - node_addr:
      Remote node address.

  - OUT - None

Return Value

  If successful, `pwrfip_sm_var_create()` returns a new `struct pwrfip_var` pointer.
  If unsuccessful, `pwrfip_sm_var_create()` returns NULL and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - ENOMEM:
    Memory allocation error.

  - PWRFIP_ERR_AELE_NOT_STOP:
    AE/LE is currently running. Stop it before trying to create new objects.

  - PWRFIP_ERR_CFG_VAR_EXIST:
    Impossible to create this variable. The AE/LE context already contains a variable with this FIP identifier.

  - PWRFIP_ERR_CFG_VAR_DIR:
    An update of the variable tried to be applied; but it’s impossible to change the direction of the variable (prod/cons) for this FIP identifier.

  - PWRFIP_ERR_CFG_MSG_PROD:
    Impossible to link a produced message on this FIP identifier. A consumed variable is already attached to it.

  - PWRFIP_ERR_CFG_MSG_DIR:
    A FIP production message is already attached to this FIP identifier; so it is impossible to change the production channel.

Example

    int main(int argc, char *argv[])
    {
        int err = 0;
        struct pwrfip_node *node;
        struct pwrfip_aele *al;

        /**
         * Node initialization.
         * Note: We assume here that the local node created has a FIP address = 1
         */
        /*...*/

        /**
         * Create an aele context.
         * Note: When the AE/LE is created, the following SM-MPS variables are
         * automatically created: 0x9003, 0x9002, 0x10XY, 0x11XY, 0x14XY where
         * XY is the local node address (here, FIP address = 1).
         * If the node is master (ba active), 0x9002 and 0x9003 variables will
         * be automatically produced and updated by the library; otherwise they
         * will only be consumed.
         * Moreover 0x10XY, 0x11XY, 0x14XY are always automatically produced and
         * updated by the library.
         */
        al = pwrfip_aele_create(node);
        if (!al) {
            printf("aele creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /**
         * Creates other sm-mps variables to consume.
         * Note: In this example, the local station will be connected to the remote
         * stations 2 and 3; and we would like to be able to read their system
         * management variables. So we create them.
         */
        /* => creates consumed SM-MPS variables: 0x1002, 0x1102, 0x1402 */
        pwrfip_sm_var_create(al, PWRFIP_SM_VAR_IDENT, 2);
        pwrfip_sm_var_create(al, PWRFIP_SM_VAR_REPORT, 2);
        pwrfip_sm_var_create(al, PWRFIP_SM_VAR_PRESENCE, 2);

        /* => creates consumed SM-MPS variables: 0x1003, 0x1103, 0x1403 */
        pwrfip_sm_var_create(al, PWRFIP_SM_VAR_IDENT, 3);
        pwrfip_sm_var_create(al, PWRFIP_SM_VAR_REPORT, 3);
        pwrfip_sm_var_create(al, PWRFIP_SM_VAR_PRESENCE, 3);

        /**
         * Other tasks
         */
        /* ... */

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.3.6. var_create

Description

  Creates a FIP variable inside an user’s application context.

Prototype

    struct pwrfip_var *pwrfip_var_create(struct pwrfip_aele *aele,
                    struct pwrfip_var_cfg *cfg)

Parameters

  - IN

    - aele:
      Pointer to a user’s application context (AE/LE).

    - cfg:
      Pointer to a variable’s configuration structure.
      See `struct pwrfip_var_cfg`.

  - OUT - None

Return Value

  If successful, `pwrfip_var_create()` returns a new `struct pwrfip_var` pointer.
  If unsuccessful, `pwrfip_var_create()` returns NULL and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - ENOMEM:
    Memory allocation error.

  - PWRFIP_ERR_AELE_NOT_STOP:
    AE/LE is currently running. Stop it before trying to create new objects.

  - PWRFIP_ERR_CFG_VAR_EXIST:
    Impossible to create this variable. The AE/LE context already contains a variable with this FIP identifier.

  - PWRFIP_ERR_CFG_VAR_DIR:
    An update of the variable tried to be applied; but it’s impossible to change the direction of the variable (prod/cons) for this FIP identifier.

  - PWRFIP_ERR_CFG_MSG_PROD:
    Impossible to link a produced message on this FIP identifier. A consumed variable is already attached to it.

  - PWRFIP_ERR_CFG_MSG_DIR:
    A FIP production message is already attached to this FIP identifier; so it is impossible to change the production channel.

Example

    void sync_var_handler(struct pwrfip_node *node,
        struct pwrfip_var *var, struct pwrfip_event *evt);

    static struct pwrfip_var_cfg prod_var_cfg = {
        .type = PWRFIP_VAR_TYPE_PROD,
        .id = 0x3800,
        .prod.payload_bsz = 8,
        .prod.flags = \
            /* enable prod status */
            PWRFIP_VAR_FLAGS_REFRESH | \
            /* enable aper var request */
            PWRFIP_VAR_FLAGS_APER_VAR_REQ | \
            /* enable aper msg request */
            PWRFIP_VAR_FLAGS_APER_MSG_REQ,
        .prod.refreshment_ustime = 80000, /* 80ms */
        .prod.evt_type = PWRFIP_EVT_TYPE_NONE,
        .pwrfip_var_handler = NULL,
    };

    static struct pwrfip_var_cfg cons_var_cfg = {
        .type = PWRFIP_VAR_TYPE_CONS,
        .id = 0x3801,
        .cons.payload_bsz = 8,
        .cons.flags = \
            /* enable prod status */
            PWRFIP_VAR_FLAGS_REFRESH | \
            /* enable promptness checking */
            PWRFIP_VAR_FLAGS_PROMPT | \
            /* enable pdu + len bytes checking */
            PWRFIP_VAR_FLAGS_CHK_PDU_LEN,
        .cons.promptness_ustime = 100000, /* 100ms */
        .cons.evt_type = PWRFIP_EVT_TYPE_NONE,
        .pwrfip_var_handler = NULL,
    };

    static struct pwrfip_var_cfg sync_var_cfg = {
        .type = PWRFIP_VAR_TYPE_SYNC,
        .id = 0x3000,
        .pwrfip_var_handler = sync_var_handler,
    };

    int main(int argc, char *argv[])
    {
        int err = 0;
        struct pwrfip_node *node;
        struct pwrfip_aele *al;
        struct pwrfip_var *prod_var, *cons_var, *sync_var;

        /**
         * Node initialization
         */
        /*...*/

        /* create an aele context */
        al = pwrfip_aele_create(node);
        if (!al) {
            printf("aele creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create a production variable */
        prod_var = pwrfip_var_create(al, &prod_var_cfg);
        if (!prod_var) {
            printf("production variable creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create a consumption variable */
        cons_var = pwrfip_var_create(al, &cons_var_cfg);
        if (!cons_var) {
            printf("consumption variable creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create a synchronization variable */
        sync_var = pwrfip_var_create(al, &sync_var_cfg);
        if (!sync_var) {
            printf("synchronization variable creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /**
         * Other tasks
         */
        /* ... */

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.3.7. var_delete

Description

  Deallocates a specific variable from an application entity (AE/LE).

Prototype

    int pwrfip_var_delete(struct pwrfip_var *var)

Parameters

  - IN

    - var:
      Pointer to the variable to delete.
      See `struct pwrfip_var`.

  - OUT - None

Return Value

  If successful, `pwrfip_var_delete()` returns 0.
  If unsuccessful, `pwrfip_var_delete()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameter.

  - PWRFIP_ERR_AELE_NOT_STOP:
    AE/LE attached to this variable is currently running. Stop it before try to delete it.

### 4.4. Bus Arbiter

#### 4.4.1. ba_mcycle_create

Description

  This function creates a new macrocycle (or Bus Arbiter table) attached to a FIP node.

| To support this function, the FIP node has to set Master capability.

Prototype

    struct pwrfip_ba_mcycle *pwrfip_ba_mcycle_create(
                                struct pwrfip_node *node,
                                struct pwrfip_ba_mcycle_cfg *cfg)

Parameters

  - IN

    - node:
      Pointer to the FIP node where to create the new macrocycle.
      See `struct pwrfip_node`.

    - cfg:
      Pointer to a macrocycle configuration structure.
      See `struct pwrfip_ba_mcycle_cfg`.

  - OUT - None

Return Value

  If successful, `pwrfip_ba_mcycle_create()` returns a new `struct pwrfip_ba_mcycle` pointer (opaque structure).
  If unsuccessful, `pwrfip_ba_mcycle_create()` returns NULL and sets errno to one of the following values:

  - EINVAL:
    Invalid node or macrocycle configuration structure.

  - ENOMEM:
    Memory allocation error.

  - PWRFIP_ERR_MCYCLE_WIND_UNKNOWN:
    Invalid macrocycle window type (see `enum pwrfip_ba_wind_type`).

  - PWRFIP_ERR_MCYCLE_WIND_COUNT:
    Macrocycle window count has to be greater than 0.

  - PWRFIP_ERR_MCYCLE_PER_WIND_REQ_COUNT:
    Requests count inside a macrocycle periodic window has to be greater than 0.

  - PWRFIP_ERR_MCYCLE_PER_WIND_REQ_UNKNOWN:
    Invalid request type inside a macrocycle periodic window.
    Requests allowed are only ID_DAT and ID_MSG type.

  - PWRFIP_ERR_MCYCLE_WIND_TIME_INC:
    Overlap on macrocycle windows end times.
    The `.end_ustime` field present in the configuration of certain types of bus arbiter window is a time relative to the beginning of the macrocycle.
    This time must therefore be increasing as you go through the configuration list.

  - PWRFIP_ERR_MCYCLE_WIND_END:
    The macrocyle configuration must end with a time window (wait).

Example

    #define TST_BA_PER_REQ_COUNT 3
    static struct pwrfip_ba_request tst_ba_per_req[TST_BA_PER_REQ_COUNT] = {
        {
            .type = PWRFIP_BA_ID_DAT,
            .id = 0x3800,
        },
        {
            .type = PWRFIP_BA_ID_DAT,
            .id = 0x3801,
        },
        {
            .type = PWRFIP_BA_ID_DAT,
            .id = 0x9003,
        },
    };

    static struct pwrfip_ba_wind_cfg tst_ba_wind_cfg[2][4] = {
        /* ba mcycle 1 */
        {
            /* 1 - periodic variable window */
            {
                .type = PWRFIP_BA_WIND_PER,
                .per.req_cnt = TST_BA_PER_REQ_COUNT,
                .per.req_list = &tst_ba_per_req[0],
            },
            /* 2 - aperiodic message window */
            {
                .type = PWRFIP_BA_WIND_APER_MSG,
                .aper_msg.end_ustime = 15000,
            },
            /* 3 - aperiodic variable window */
            {
                .type = PWRFIP_BA_WIND_APER_VAR,
                .aper_var.end_ustime = 35000,
                .aper_var.enable_testp = 1, /* enable presence test if no other
                                             * request to dispatch */
            },
            /* 4 - resync wait window */
            {
                .type = PWRFIP_BA_WIND_WAIT,
                .wait.end_ustime = 40000,
                .wait.is_silent = 0, /* fill window with padding frames */
                .wait.is_ext_resync = 0, /* internal resynchronization */
            },
        },
        /* ba mcycle 2 */
        {
            /* 1 - periodic variable window */
            {
                .type = PWRFIP_BA_WIND_PER,
                .per.req_cnt = TST_BA_PER_REQ_COUNT,
                .per.req_list = &tst_ba_per_req[0],
            },
            /* 2 - aperiodic message window */
            {
                .type = PWRFIP_BA_WIND_APER_MSG,
                .aper_msg.end_ustime = 75000,
            },
            /* 3 - resync wait window */
            {
                .type = PWRFIP_BA_WIND_WAIT,
                .wait.end_ustime = 80000,
                .wait.is_silent = 0, /* fill window with padding frames */
                .wait.is_ext_resync = 0, /* internal resynchronization */
            },
            /* no other window */
            {
                .type = 0,
            }
        },
    };

    static struct pwrfip_ba_mcycle_cfg tst_ba_mcycle_cfg[2] = {
        /* ba mcycle 1 */
        {
            .wind_cnt = 4,
            .wind_list = &tst_ba_wind_cfg[0][0],
        },
        /* ba mcycle 2 */
        {
            .wind_cnt = 3,
            .wind_list = &tst_ba_wind_cfg[1][0],
        },
    };

    int main(int argc, char *argv[])
    {
        int err = 0;
        struct pwrfip_node *node;
        struct pwrfip_ba_mcycle *mcycle[2];

        /**
         * Node initialization
         */
        /*...*/

        /* create two bus arbiter macrocycles */
        for (i = 0; i < 2; ++i) {
            struct pwrfip_ba_mcycle_cfg *mcycle_cfg = &tst_ba_mcycle_cfg[i];

            mcycle[i] = pwrfip_ba_mcycle_create(node, mcycle_cfg);
            if (!mcycle[i]) {
                /* get error */*
                printf("macrocycle creation failed: %s\n", pwrfip_strerror(errno));
                err = -1;
                goto end;
            }
        }

        /**
         * Other tasks
         */
        /* ... */

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.4.2. ba_mcycle_delete

Description

  The function `pwrfip_ba_mcycle_delete()` deallocates a specific macrocycle.

Prototype

    int pwrfip_ba_mcycle_delete(struct pwrfip_ba_mcycle *mcycle)

Parameters

  - IN

    - mcycle:
      Macrocycle to delete.

  - OUT - None

Return Value

  If successful, `pwrfip_ba_mcycle_delete()` returns 0.
  If unsuccessful, `pwrfip_ba_mcycle_delete()` returns -1 and sets errno to one of the following values:

  - PWRFIP_ERR_BA_NOT_STOP:
    The macrocycle is currently running. Stop it before try to delete it.

#### 4.4.3. ba_startup_calculate

Description

  Tool function to calculate compliant start-up and election times for a bus arbiter in an environment where multiple FIP nodes are competing to become Master.

Prototype

    int pwrfip_ba_startup_calculate(uint32_t *stup_ustime, uint32_t *elec_ustime,
            struct pwrfip_ba_startup_cfg *cfg)

Parameters

  - IN

    - cfg:
      Input parameters for time calculation.
      See `struct pwrfip_ba_startup_cfg`.

  - OUT

    - stup_ustime:
      BA start-up time calculated in microseconds.

    - elec_ustime:
      BA election time calculated in microseconds.

Return Value

  If successful, `pwrfip_ba_startup_calculate()` returns 0.
  If unsuccessful, `pwrfip_ba_startup_calculate()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_BA_STUP_PHY_ADDR_INVALID:
    Local physical address exceeds maximum physical address given.

  - PWRFIP_ERR_BA_STUP_PRIO_INVALID:
    Local priority is higher than maximum one given.

| BA Priority Priority range is between [0;15], with 0 the highest priority.

- PWRFIP_ERR_BA_STUP_TS_INVALID:
  Silence Time input parameter should not be 0.

#### 4.4.4. ba_start

Description

  Starts a specific macrocycle for the master node attached.

Prototype

    int pwrfip_ba_start(struct pwrfip_ba_mcycle *mcycle)

Parameters

  - IN

    - mcycle:
      Macrocycle to start.

  - OUT - None

Return Value

  If successful, `pwrfip_ba_start()` returns 0.
  If unsuccessful, `pwrfip_ba_start()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid macrocycle pointer.

  - PWRFIP_ERR_BA_NOT_STOP:
    The node has already a running macrocycle.
    Use `pwrfip_ba_commute()` function instead.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.4.5. ba_stop

Description

  Stops the macrocycle of a specific FIP node.

Prototype

    int pwrfip_ba_stop(struct pwrfip_node *node)

Parameters

  - IN

    - node:
      FIP node to query.
      See `struct pwrfip_node`.

  - OUT - None

Return Value

  If successful, `pwrfip_ba_stop()` returns 0.
  If unsuccessful, `pwrfip_ba_stop()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid node pointer.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.4.6. ba_commute

Description

  Switch to the execution of another FIP macrocycle.

Prototype

    int pwrfip_ba_commute(struct pwrfip_ba_mcycle *mcycle)

Parameters

  - IN

    - mcycle:
      Pointer to the new macrocycle to switch to.

  - OUT - None

Return Value

  If successful, `pwrfip_ba_commute()` returns 0.
  If unsuccessful, `pwrfip_ba_commute()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid macrocycle pointer.

  - PWRFIP_ERR_BA_NOT_RUN:
    The node does not have a running macrocycle.
    Use `pwrfip_ba_start()` function instead.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.4.7. ba_status_get

Description

  Gets the bus arbiter status for a given FIP node.

Prototype

    int pwrfip_ba_status_get(struct pwrfip_node *node, struct pwrfip_ba_status *status)

Parameters

  - IN

    - node:
      FIP node to query.
      See `struct pwrfip_node`.

  - OUT

    - status:
      Pointer to an output `struct pwrfip_ba_status`.

Return Value

  If successful, `pwrfip_ba_status_get()` returns 0.
  If unsuccessful, `pwrfip_ba_status_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

### 4.5. Messages

#### 4.5.1. msg_send

Description

  Writes a FIP message to the local coprocessor database.

Prototype

    int pwrfip_msg_send(struct pwrfip_msg *msg)

Parameters

  - IN

    - msg:
      Pointer to the target message to write.
      See `struct pwrfip_msg`.

  - OUT

    - msg:
      Message’s updated info.
      See `struct pwrfip_msg` (`.epoch` and `.error` fields).

Return Value

  If successful, `pwrfip_msg_send()` returns 0.
  If unsuccessful, `pwrfip_msg_send()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_INVALID_CTX:
    The AE/LE context attached to the message object does not match that of the running node.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is not running. It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

Remarks

  There are two possible error levels for this operation:

  1. The error returned by the `pwrfip_msg_send()` function is related to a context error inside the library, or a communication error with the coprocessor.
     This type of error is quite critical since it indicates a malfunction of the library.

  2. The `.error` field returned in the `struct pwrfip_msg` (see `enum pwrfip_msg_err_code`) relates directly to the FIP frame state written to the network.
     It is an indicator of the quality of the frame written.

Example

    static struct pwrfip_msg_cfg prod_msg_cfg = {
        .type = PWRFIP_MSG_TYPE_SEND,
        .tx.channel = PWRFIP_MSG_TX_CH_APER,
        .tx.ack_mode = PWRFIP_MSG_TX_ACK_MODE_SDA,
        /* local data link layer address: 0x0C0000 */
        .hdr.src.seg = 0,
        .hdr.src.lsap = 0x0C00, /* ssap */
        /* remote data link layer address: 0x0C0100 */
        .hdr.dst.seg = 0,
        .hdr.dst.lsap = 0x0C01, /* dsap (=target) */
        .pwrfip_msg_handler = NULL,
    };

    int main(int argc, char *argv[])
    {
        int i, err = 0;
        struct pwrfip_node *node;
        struct pwrfip_aele *al;
        struct pwrfip_msg *prod_msg;
        uint16_t w_counter = 0;

        /**
         * Node initialization
         */
        /*...*/

        /* create an aele context */
        al = pwrfip_aele_create(node);
        if (!al) {
            printf("aele creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create a production message */
        prod_msg = pwrfip_msg_create(al, &prod_msg_cfg);
        if (!prod_msg) {
            printf("production message creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* node startup (slave) */
        err = pwrfip_node_start(al, NULL, 0);
        if (err) {
            printf("node startup failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* writing loop */
        for(;;) {
            /* update msg payload */
            w_counter++;
            prod_msg->bsz = sizeof(w_counter);
            memcpy(prod_msg->buffer, &w_counter, prod_msg->bsz);

            /* send it to fip network */
            if (pwrfip_msg_send(prod_msg)) {
                printf("w_msg[header: src=0x%08x dst=0x%08x] failed: %s\n",
                    prod_msg->hdr.src.addr, prod_msg->hdr.dst.addr,
                    pwrfip_strerror(errno));
                /* we consider this error as fatal error; so we
                 * stop the test */
                break;
            }

            /* check msg state errors */
            if (prod_msg->error) {
                printf("w_msg[header: src=0x%08x dst=0x%08x] state error: %d\n",
                    prod_msg->hdr.src.addr, prod_msg->hdr.dst.addr,
                    prod_msg->error);
            }

            usleep(100000); /* 100ms */
        }

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.5.2. msg_tx_channel_purge

Description

  Purges the target periodic/aperiodic message TX channel.

Prototype

    int pwrfip_msg_tx_channel_purge(struct pwrfip_node *node,
                    enum pwrfip_msg_tx_channel channel,
                    uint16_t *purge_cnt, uint8_t *ch_error);

Parameters

  - IN

    - node:
      Pointer to the target node.
      See `struct pwrfip_node`.

    - channel:
      Message TX channel to purge.
      See `enum pwrfip_msg_tx_channel`.

  - OUT

    - purge_cnt:
      Number of messages purged.

    - ch_error:
      Channel error.
      See `enum pwrfip_msg_err_code`.

Return Value

  If successful, `pwrfip_msg_tx_channel_purge()` returns 0.
  If unsuccessful, `pwrfip_msg_tx_channel_purge()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is not running. It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

### 4.6. Node

#### 4.6.1. node_init

Description

  Creates a new FIP node context inside the library and load it to the local database of a binded coprocessor.
  This is the main step in creating a FIP node.

Prototype

    struct pwrfip_node *pwrfip_node_init(struct pwrfip_node_cfg *cfg)

Parameters

  - IN

    - cfg:
      Pointer to the FIP node configuration.
      See `struct pwrfip_node_cfg`.

  - OUT - None

Return Value

  If successful, `pwrfip_node_init()` returns a new `struct pwrfip_node` pointer.
  If unsuccessful, `pwrfip_node_init()` returns NULL and sets errno to one of the following values:

  - EINVAL:
    Invalid input configuration.

  - ENOMEM:
    Memory allocation error.

  - PWRFIP_ERR_NODE_BSS_OVERFLOW:
    Node BSS overflow.
    You should reduce the FIFO sizes of the node.

  - PWRFIP_ERR_NODE_HANDLER_MISSING:
    Some user handlers are mandatory to continue the node creation:

    - pwrfip_reset_handler

    - pwrfip_error_handler

  - PWRFIP_ERR_NODE_FRM_TYPE_INVALID:
    Invalid frame type configuration. Should be:

    - PWRFIP_FRM_FIP

    - PWRFIP_FRM_WORLDFIP

  - PWRFIP_ERR_NODE_BITRATE_INVALID:
    Invalid FIP bitrate configuration. Should be:

    - PWRFIP_BITRATE_31K25

    - PWRFIP_BITRATE_1M

    - PWRFIP_BITRATE_2M5

    - PWRFIP_BITRATE_5M

  - PWRFIP_ERR_NODE_TR_INVALID:
    Invalid FIP turnaround time. Range should be:

    - @31.25Kbps : min=320us, max=8232us, default=424us

    - @1Mbps : min=10us, max=258us, default=30us

    - @2.5Mbps : min=13us, max=103us, default=30us

    - @5Mbps : min=13us, max=103us, default=32us

    - @12.5Mbps : min=13us, max=103us, default=32us

    - @25Mbps : min=13us, max=103us, default=32us

  - PWRFIP_ERR_NODE_TS_INVALID:
    Invalid FIP silence time. Range should be:

    - @31.25Kbps : min=2880us, max=65535us, default=4096us

    - @1Mbps : min=70us, max=65535us, default=150us

    - @2.5Mbps : min=36us, max=65535us, default=96us

    - @5Mbps : min=36us, max=65535us, default=92us

    - @12.5Mbps : min=36us, max=65535us, default=92us

    - @25Mbps : min=36us, max=65535us, default=92us

  - PWRFIP_ERR_NODE_RX_MSG_FIFO_SZ:
    Invalid queue size for message consumption.
    Range value should be: [1..64].

  - PWRFIP_ERR_NODE_RX_MSG_SEG_CAP:
    Invalid segment capability for consumption message. Should be:

    - PWRFIP_MSG_SEG_IGNORE

    - PWRFIP_MSG_SEG_ACCEPT_ALL

    - PWRFIP_MSG_SEG_ACCEPT_LTD

  - PWRFIP_ERR_NODE_TX_MSG_FIFO_SZ:
    Invalid queue size for message transmission.
    Range value should be: [1..64].

  - PWRFIP_ERR_NODE_TX_MSG_REPEAT:
    Invalid maximum repeats for acknowledged message transmission.
    Range value should be: [0..3].

  - PWRFIP_ERR_NODE_BA_STUP_TIMES:
    The bus arbiter election time must be shorter than the start-up time.

  - PWRFIP_ERR_NODE_BA_REQ_FIFO_SZ:
    Invalid queue size for BA requests.
    Range value should be: [1..64].

  - PWRFIP_ERR_DEV_ALREADY_BIND:
    The provided device is already bound to another FIP node session.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

  - [..]:
    Other posix errors related to a file opening error

Example 1 - PCI/PCIe PowerFIP

    void usr_rst_handler(struct pwrfip_node *node)
    {
        /* calling the reset function for a pci/pcie device */
        if (pwrfip_device_reset(node->infos->cfg.dev)) {
            printf("reset failed: %s\n", pwrfip_strerror(errno));
            return;
        }
        _print(src, evt, "reset coprocessor component (powerfip) done\n");
    }

    void usr_err_handler(struct pwrfip_node *node,
            enum pwrfip_error_code code)
    {
        printf("error_handler: %s (err_code=%d)\n",
            pwrfip_strerror(code), code);
    }

    int main(int argc, char *argv[])
    {
        int err = 0;
        struct pwrfip_dev *dev;
        struct pwrfip_node *node;
        struct pwrfip_node_cfg cfg;

        /* pwrfip lib initialization [mandatory] */
        if (pwrfip_init()) {
            printf("cannot init pwrfip library: %s\n",
                pwrfip_strerror(errno));
            return -1;
        }

        /* open a pci/pcie device (1st index) */
        dev = pwrfip_device_open(1);
        if (!dev) {
            printf("cannot open device: %s\n",
                pwrfip_strerror(errno));
            pwrfip_exit();
            return -1;
        }

        /**
         * Node initialization:
         * Minimal set-up for a PCI/PCIe device
         */
        cfg.fip_phy_addr = 1; /* fip node addr = 0x01 */
        cfg.fip_seg_num = 0; /* fip node belongs to fip segment 0 */
        cfg.fip_frm_type = PWRFIP_FRM_WORLDFIP; /* WorldFIP frame (IEC) */
        cfg.fip_bitrate = PWRFIP_BITRATE_1M; /* 1Mbps */
        cfg.turn_around_ustime = 0; /* default TR time for 1Mbps (30us) */
        cfg.silence_ustime = 0; /* default TS time for 1Mbps (150us) */
        cfg.enable_bimedium = 0; /* mono-medium topology (just one channel) */
        cfg.msg.enable = 0; /* fip messaging not supported */
        cfg.ba.enable = 0; /* no master capability for this node */
        cfg.ident.manufacturer_name = "MyVendorName\0";
        cfg.ident.model_name = "MyModelName\0";
        cfg.ident.revision = 0x10; /* v1.0 */
        cfg.dev = dev; /* coprocessor attachment: pci/pcie device to bind */
        cfg.pwrfip_error_handler = usr_err_handler; /* local handler to notify
                                                       the internal errors of
                                                       the library */
        cfg.pwrfip_reset_handler = usr_rst_handler; /* local handler to reset
                                                       the bound device */

        node = pwrfip_node_init(&cfg);
        if (!node) {
            printf("node initialization failed: %s\n",
                pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /**
         * Other tasks
         */
        /* ... */

    end:
        /**
         * Node exit
         */
        /*...*/

        /* close device */
        pwrfip_device_close(dev);

        /* pwrfip lib exit [mandatory] */
        pwrfip_exit();
        return err;
    }

Example 2 - PowerFIP-CC [STM32 Host]

    void usr_rst_handler(struct pwrfip_node *node)
    {
        /* ... */
    }

    void fip_cc_ioread32(void *hnd, uint32_t *addr, uint32_t *value)
    {
        HAL_SRAM_Read_32b((SRAM_HandleTypeDef *) hnd, addr, value, 1);
    }

    void fip_cc_iowrite32(void *hnd, uint32_t *addr, uint32_t value)
    {
        HAL_SRAM_Write_32b((SRAM_HandleTypeDef *) hnd, addr, &value, 1);
    }

    void usr_err_handler(struct pwrfip_node *node,
            enum pwrfip_error_code code)
    {
        printf("error_handler: %s (err_code=%d)\n",
            pwrfip_strerror(code), code);
    }

    int main(int argc, char *argv[])
    {
        int err = 0;
        struct pwrfip_node *node;
        struct pwrfip_node_cfg cfg;

        /* pwrfip lib initialization [mandatory] */
        if (pwrfip_init()) {
            printf("cannot init pwrfip library: %s\n",
                pwrfip_strerror(errno));
            return -1;
        }

        /**
         * Node initialization:
         * Minimal set-up to manage PowerFIP controller via DPM
         */
        cfg.fip_phy_addr = 1; /* fip node addr = 0x01 */
        cfg.fip_seg_num = 0; /* fip node belongs to fip segment 0 */
        cfg.fip_frm_type = PWRFIP_FRM_WORLDFIP; /* WorldFIP frame (IEC) */
        cfg.fip_bitrate = PWRFIP_BITRATE_1M; /* 1Mbps */
        cfg.turn_around_ustime = 0; /* default TR time for 1Mbps (30us) */
        cfg.silence_ustime = 0; /* default TS time for 1Mbps (150us) */
        cfg.enable_bimedium = 0; /* mono-medium topology (just one channel) */
        cfg.msg.enable = 0; /* fip messaging not supported */
        cfg.ba.enable = 0; /* no master capability for this node */
        cfg.ident.manufacturer_name = "MyVendorName\0";
        cfg.ident.model_name = "MyModelName\0";
        cfg.ident.revision = 0x10; /* v1.0 */

        /* STM32 FMC attachement */
        cfg.proc.base_addr = 0x60000000; // fmc bank1 address
        cfg.proc.hnd = &hsram1;
        cfg.proc.pwrfip_ioread32 = fip_cc_ioread32;
        cfg.proc.pwrfip_iowrite32 = fip_cc_iowrite32;

        cfg.pwrfip_error_handler = usr_err_handler; /* local handler to notify
                                                       the internal errors of
                                                       the library */
        cfg.pwrfip_reset_handler = usr_rst_handler; /* local handler to reset
                                                       the bound device */

        node = pwrfip_node_init(&cfg);
        if (!node) {
            printf("node initialization failed: %s\n",
                pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /**
         * Other tasks
         */
        /* ... */

    end:
        /**
         * Node exit
         */
        /*...*/

        /* pwrfip lib exit [mandatory] */
        pwrfip_exit();
        return err;
    }

#### 4.6.2. node_exit

Description

  Stops the coprocessor and deallocates all resources attached to the FIP node inside the library.

Prototype

    int pwrfip_node_exit(struct pwrfip_node *node)

Parameters

  - IN

    - node:
      Pointer to the FIP node to exit.
      See `struct pwrfip_node`.

  - OUT - None

Return Value

  If successful, `pwrfip_node_exit()` returns 0.
  If unsuccessful, `pwrfip_node_exit()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameter.

  - PWRFIP_ERR_DEV_IRQ_HANDLER_STOPPED:
    Internal IRQ handler for PCI/PCIe device is already stopped.

  - PWRFIP_ERR_AELE_NOT_STOP:
    Cannot stop the Application/Layer entity. The exit procedure has therefore failed.

  - PWRFIP_ERR_BA_NOT_STOP:
    Cannot stop the bus arbiter FSM. The exit procedure has therefore failed.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.6.3. node_status_get

Description

  Get the FSM status of the FIP node.

Prototype

    int pwrfip_node_status_get(struct pwrfip_node *node,
                    struct pwrfip_node_status *status)

Parameters

  - IN

    - node:
      Pointer to the target FIP node.
      See `struct pwrfip_node`.

  - OUT

    - status:
      Pointer to an output `struct pwrfip_node_status`.

Return Value

  If successful, `pwrfip_node_status_get()` returns 0.
  If unsuccessful, `pwrfip_node_status_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

Example

    static const char *pwrfip_node_state_str[_PWRFIP_NODE_STATE_MAX] = {
        /* PWRFIP_NODE_STATE_INITIAL */
        "initial",
        /* PWRFIP_NODE_STATE_LOADED */
        "loaded",
        /* PWRFIP_NODE_STATE_READY */
        "ready",
        /* PWRFIP_NODE_STATE_RUNNING */
        "running",
    };

    static const char *pwrfip_node_op_str[_PWRFIP_NODE_OP_MAX] = {
        /* _PWRFIP_NODE_OP_UNKNOWN */
        "unknown",
        /* PWRFIP_NODE_OP_WAIT_RX_RP_FRM */
        "rx rp frame",
        /* PWRFIP_NODE_OP_WAIT_TX_RP_FRM */
        "tx rp frame",
        /* PWRFIP_NODE_OP_WAIT_RX_ID_FRM */
        "rx id frame",
        /* PWRFIP_NODE_OP_WAIT_TX_ID_FRM */
        "tx id frame",
    };

    int main(int argc, char *argv[])
    {
        int err = 0;
        struct pwrfip_node *node;
        struct pwrfip_node_status n_status;

        /**
         * Node initialization
         */
        /*...*/

        /* get node status */
        err = pwrfip_node_status_get(node, &n_status);
        if (err) {
            printf("node status getter failed: %s\n", pwrfip_strerror(errno));
            goto end;
        }

        printf("node_status\n");
        printf("  node_state    : %d (%s)\n", n_status.state,
                pwrfip_node_state_str[n_status.state]);
        printf("  node_op       : %d (%s)\n", n_status.op,
                pwrfip_node_op_str[n_status.op]);

        /**
         * Other tasks
         */
        /* ... */

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.6.4. node_report_get

Description

  Gets the full diagnostic report of the FIP node.

Prototype

    int pwrfip_node_report_get(struct pwrfip_node *node,
                    struct pwrfip_node_report *report)

Parameters

  - IN

    - node:
      Pointer to the target FIP node.
      See `struct pwrfip_node`.

  - OUT

    - report:
      Pointer to an output `struct pwrfip_node_report`.

Return Value

  If successful, `pwrfip_node_report_get()` returns 0.
  If unsuccessful, `pwrfip_node_report_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

Example

    static const char *pwrfip_node_state_str[_PWRFIP_NODE_STATE_MAX] = {
        /* PWRFIP_NODE_STATE_INITIAL */
        "initial",
        /* PWRFIP_NODE_STATE_LOADED */
        "loaded",
        /* PWRFIP_NODE_STATE_READY */
        "ready",
        /* PWRFIP_NODE_STATE_RUNNING */
        "running",
    };

    static const char *pwrfip_ba_state_str[_PWRFIP_BA_STATE_MAX] = {
        /* PWRFIP_BA_STATE_INITIAL */
        "initial",
        /* PWRFIP_BA_STATE_READY */
        "ready",
        /* PWRFIP_BA_STATE_STARTING */
        "starting",
        /* PWRFIP_BA_STATE_IDLE */
        "idle",
        /* PWRFIP_BA_STATE_RUNNING */
        "running",
    };

    static const char *pwrfip_node_op_str[_PWRFIP_NODE_OP_MAX] = {
        /* _PWRFIP_NODE_OP_UNKNOWN */
        "unknown",
        /* PWRFIP_NODE_OP_WAIT_RX_RP_FRM */
        "rx rp frame",
        /* PWRFIP_NODE_OP_WAIT_TX_RP_FRM */
        "tx rp frame",
        /* PWRFIP_NODE_OP_WAIT_RX_ID_FRM */
        "rx id frame",
        /* PWRFIP_NODE_OP_WAIT_TX_ID_FRM */
        "tx id frame",
    };

    static const char *pwrfip_ba_wind_str[_PWRFIP_BA_WIND_TYPE_MAX] = {
        /* _PWRFIP_BA_WIND_TYPE_NONE */
        "none",
        /* PWRFIP_BA_WIND_PER */
        "periodic",
        /* PWRFIP_BA_WIND_APER_VAR */
        "aper. var",
        /* PWRFIP_BA_WIND_APER_MSG */
        "aper. msg",
        /* PWRFIP_BA_WIND_WAIT */
        "wait",
    };

    int main(int argc, char *argv[])
    {
        int err = 0;
        struct pwrfip_node *node;
        struct pwrfip_node_report n_report; /* full report */
        uint16_t m_state; /* medium state */

        /**
         * Node initialization
         */
        /*...*/

        /**
         * Node startup
         */
        /*...*/

        /* get node report */
        err = pwrfip_node_report_get(node, &n_report);
        if (err) {
            printf("node report getter failed: %s\n", pwrfip_strerror(errno));
            goto end;
        }

        m_state = n_report.medium_status.state;
        printf("** coprocessor report:\n");
        printf("  node_state    : %d (%s)\n", n_report.node_status.state,
                pwrfip_node_state_str[n_report.node_status.state]);
        printf("  node_op       : %d (%s)\n", n_report.node_status.op,
                pwrfip_node_op_str[n_report.node_status.op]);
        printf("  ba_state      : %d (%s)\n", n_report.ba_status.state,
                pwrfip_ba_state_str[n_report.ba_status.state]);
        printf("  ba_window     : %d (%s)\n", n_report.ba_status.window,
                pwrfip_ba_wind_str[n_report.ba_status.window]);
        printf("  medium_state  : 0x%04x\n", m_state);
        printf("    [channel 1]\n");
        printf("      enable    : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH1_VALID) ? "yes": "no");
        printf("      tx_err    : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH1_TX_ERROR) ? "yes": "no");
        printf("      watchdog  : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH1_WATCHDOG) ? "yes": "no");
        printf("    [channel 2]\n");
        printf("      enable    : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH2_VALID) ? "yes": "no");
        printf("      tx_err    : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH2_TX_ERROR) ? "yes": "no");
        printf("      watchdog  : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH2_WATCHDOG) ? "yes": "no");
        printf("  tx_err        :\n");
        printf("    ok          : %d\n", n_report.tx_err.ok);
        printf("    collision   : %d\n", n_report.tx_err.collision);
        printf("    consistency : %d\n", n_report.tx_err.consistency);
        printf("    not_fresh   : %d\n", n_report.tx_err.not_fresh);
        printf("  rx_err        :\n");
        printf("    ok          : %d\n", n_report.rx_err.ok);
        printf("    pre_mis     : %d\n", n_report.rx_err.pre_mis);
        printf("    fsd_mis     : %d\n", n_report.rx_err.fsd_mis);
        printf("    fsd_unk     : %d\n", n_report.rx_err.fsd_unk);
        printf("    fed_mis     : %d\n", n_report.rx_err.fed_mis);
        printf("    crc_bad     : %d\n", n_report.rx_err.crc_bad);
        printf("    pdu_bad     : %d\n", n_report.rx_err.pdu_bad);
        printf("    len_bad     : %d\n", n_report.rx_err.len_bad);
        printf("    not_fresh   : %d\n", n_report.rx_err.not_fresh);
        printf("    not_prompt  : %d\n", n_report.rx_err.not_prompt);

        /**
         * Other tasks
         */
        /* ... */

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.6.5. node_start

Description

  Starts the FIP node.
  The user’s application data (AE/LE) as well as the desired macrocycles - if the node has a master capability - are loaded into the local coprocessor database. Then, the node connects to the FIP network in passive mode (slave agent).

| To switch the node to active mode (master agent), use `pwrfip_ba_start()` function after this call.

Prototype

    int pwrfip_node_start(struct pwrfip_aele *aele,
                    struct pwrfip_ba_mcycle **mcycle_list, int mcycle_cnt)

Parameters

  - IN

    - aele:
      Pointer to the application context (AE/LE: FIP variables/messages) to be loaded to the coprocessor (opaque structure).

    - mcycle_list:
      List of pointers to the macrocycles to be loaded (opaque structures).

    - mcycle_cnt:
      Number of macrocycles to be loaded in the FIP coprocessor.

  - OUT - None

Return Value

  If successful, `pwrfip_node_start()` returns 0.
  If unsuccessful, `pwrfip_node_start()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_AELE_NOT_STOP:
    The application context to be loaded is already active elsewhere.

  - PWRFIP_ERR_INVALID_CTX:
    A macrocycle to be loaded do not belong to the same FIP node as the application context (AE/LE).

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.6.6. node_stop

Description

  Disconnects the FIP node from the network.

| Use the `pwrfip_node_start()` function to start a new app session. No need to reinitialize the node with `pwrfip_node_init()`.

Prototype

    int pwrfip_node_stop(struct pwrfip_node *node)

Parameters

  - IN

    - node:
      Pointer to the target FIP node.
      See `struct pwrfip_node`.

  - OUT - None

Return Value

  If successful, `pwrfip_node_stop()` returns 0.
  If unsuccessful, `pwrfip_node_stop()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

### 4.7. Variables

#### 4.7.1. var_write

Description

  Writes a FIP variable to the local coprocessor database.

Prototype

    int pwrfip_var_write(struct pwrfip_var *var)

Parameters

  - IN

    - var:
      Pointer to the target variable to write.
      See `struct pwrfip_var`.

  - OUT

    - var:
      Variable’s updated info.
      See `struct pwrfip_var` (`.error` field).

Return Value

  If successful, `pwrfip_var_write()` returns 0.
  If unsuccessful, `pwrfip_var_write()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_INVALID_CTX:
    The AE/LE context attached to the variable object does not match that of the running node.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is not running. It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

Remarks

  There are two possible error levels for this operation:

  1. The error returned by the `pwrfip_var_write()` function is related to a context error inside the library, or a communication error with the coprocessor.
     This type of error is quite critical since it indicates a malfunction of the library.

  2. The `.error` field returned in the `struct pwrfip_var` (see `enum pwrfip_var_err_code`) relates directly to the FIP frame state written to the network.
     It is an indicator of the quality of the frame written (good or bad freshness).

Example

    static struct pwrfip_var_cfg prod_var_cfg = {
        .type = PWRFIP_VAR_TYPE_PROD,
        .id = 0x3800,
        .prod.payload_bsz = 8,
        .prod.flags = \
            /* enable prod status */
            PWRFIP_VAR_FLAGS_REFRESH,
        .prod.refreshment_ustime = 80000, /* 80ms */
        .prod.evt_type = PWRFIP_EVT_TYPE_NONE,
        .pwrfip_var_handler = NULL,
    };

    int main(int argc, char *argv[])
    {
        int i, err = 0;
        struct pwrfip_node *node;
        struct pwrfip_aele *al;
        struct pwrfip_var *prod_var;
        uint8_t w_byte = 0;

        /**
         * Node initialization
         */
        /*...*/

        /* create an aele context */
        al = pwrfip_aele_create(node);
        if (!al) {
            printf("aele creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create a production variable */
        prod_var = pwrfip_var_create(al, &prod_var_cfg);
        if (!prod_var) {
            printf("production variable creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* node startup (slave) */
        err = pwrfip_node_start(al, NULL, 0);
        if (err) {
            printf("node startup failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* writing loop */
        for(;;) {
            /* update var payload */
            /* for the example, we increment all the bytes of the
               frame by 1 at each write */
            w_byte++;
            memset(prod_var->buffer, w_byte, prod_var->bsz);

            /* write it to fip network */
            if (pwrfip_var_write(prod_var)) {
                printf("w_var[0x%04x] failed: %s\n", prod_var->id,
                    pwrfip_strerror(errno));
                /* we consider this error as fatal error; so we
                 * stop the test */
                break;
            }

            /* check var state errors */
            if (prod_var->error) {
                printf("w_var[0x%04x] state error: %d\n",
                    prod_var->id, prod_var->error);
            }

            usleep(5000); /* 5ms */
        }

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.7.2. var_read

Description

  Reads a FIP variable from the local coprocessor database.

Prototype

    int pwrfip_var_read(struct pwrfip_var *var)

Parameters

  - IN

    - var:
      Pointer to the target variable to read.
      See `struct pwrfip_var`.

  - OUT

    - var:
      Variable’s updated content.

Return Value

  If successful, `pwrfip_var_read()` returns 0.
  If unsuccessful, `pwrfip_var_read()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_INVALID_CTX:
    The AE/LE context attached to the variable object does not match that of the running node.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is not running. It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

Remarks

  There are two possible error levels for this operation:

  1. The error returned by the `pwrfip_var_read()` function is related to a context error inside the library, or a communication error with the coprocessor.
     This type of error is quite critical since it indicates a malfunction of the library.

  2. The `.error` field returned in the `struct pwrfip_var` (see `enum pwrfip_var_err_code`) relates directly to the FIP frame state read from the network.
     It is an indicator of the quality of the frame read (good or bad freshness/promptness), but also an indicator to know if the user configuration matches with the real frame read from the FIP network (length, PDU etc).

Example

    static struct pwrfip_var_cfg cons_var_cfg = {
        .type = PWRFIP_VAR_TYPE_CONS,
        .id = 0x3801,
        .cons.payload_bsz = 8,
        .cons.flags = \
            /* enable prod status */
            PWRFIP_VAR_FLAGS_REFRESH | \
            /* enable promptness checking */
            PWRFIP_VAR_FLAGS_PROMPT | \
            /* enable pdu + len bytes checking */
            PWRFIP_VAR_FLAGS_CHK_PDU_LEN,
        .cons.promptness_ustime = 100000, /* 100ms */
        .cons.evt_type = PWRFIP_EVT_TYPE_NONE,
        .pwrfip_var_handler = NULL,
    };

    int main(int argc, char *argv[])
    {
        int i, err = 0;
        struct pwrfip_node *node;
        struct pwrfip_aele *al;
        struct pwrfip_var *cons_var;

        /**
         * Node initialization
         */
        /*...*/

        /* create an aele context */
        al = pwrfip_aele_create(node);
        if (!al) {
            printf("aele creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create a consumption variable */
        cons_var = pwrfip_var_create(al, &cons_var_cfg);
        if (!cons_var) {
            printf("consumption variable creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* node startup (slave) */
        err = pwrfip_node_start(al, NULL, 0);
        if (err) {
            printf("node startup failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* reading loop */
        for(;;) {
            if (pwrfip_var_read(cons_var)) {
                printf("r_var[0x%04x] failed: %s\n", cons_var->id,
                    pwrfip_strerror(errno));
                /* we consider this error as fatal error; so we
                 * stop the test */
                break;
            }
            /* print var payload */
            printf("r_var[0x%04x]: ", cons_var->id);
            for (i = 0; i < cons_var->bsz; ++i)
                printf("%02x ", cons_var->buffer[i]);
            printf("\n");

            usleep(5000); /* 5ms */
        }

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.7.3. var_evt_set

Description

  Dynamically changes - inside the coprocessor database - the event sensitivity for the pointed variable.

Prototype

    int pwrfip_var_evt_set(struct pwrfip_var *var,
                    enum pwrfip_evt_type type)

Parameters

  - IN

    - var:
      Pointer to the variable on which to change the sensitivity to events.
      See `struct pwrfip_var`.

    - type:
      Type of event sensitivity (see `enum pwrfip_evt_type`):

      - PWRFIP_EVT_TYPE_NONE:
        Never report the transmission/reception of this variable to the user space.

      - PWRFIP_EVT_TYPE_PERMANENT:
        Always report the transmission/reception of this variable to the user space.

      - PWRFIP_EVT_TYPE_TEMPORARY:
        Report just once the transmission/reception of this variable to the user space.

  - OUT - None

Return Value

  If successful, `pwrfip_var_evt_set()` returns 0.
  If unsuccessful, `pwrfip_var_evt_set()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_INVALID_CTX:
    The AE/LE context attached to the variable object does not match that of the running node.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is not running. It is therefore impossible to change the variable’s event on the fly.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.7.4. var_type_set

Description

  Dynamically changes - inside the coprocessor database - the type (production or consumption) for the pointed variable.

Prototype

    int pwrfip_var_type_set(struct pwrfip_var *var,
                    enum pwrfip_var_type type);

Parameters

  - IN

    - var:
      Pointer to the variable on which to change the direction.
      See `struct pwrfip_var`.

    - type:
      Type of variable (see `enum pwrfip_var_type`):

      - PWRFIP_VAR_TYPE_CONS:
        Variable to consume.

      - PWRFIP_VAR_TYPE_PROD:
        Variable to produce.

  - OUT - None

Return Value

  If successful, `pwrfip_var_type_set()` returns 0.
  If unsuccessful, `pwrfip_var_type_set()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_INVALID_CTX:
    The AE/LE context attached to the variable object does not match that of the running node.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is not running. It is therefore impossible to change the variable’s event on the fly.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.7.5. varidlist_aper_request

Description

  Sends an aperiodic request for a list of variable IDs.

Prototype

    int pwrfip_varidlist_aper_request(struct pwrfip_node *node,
                    uint16_t *varid_list, int varid_cnt,
                    enum pwrfip_var_aper_channel_type channel,
                    uint8_t *ch_error);

Parameters

  - IN

    - node:
      Pointer to the node that makes the request.
      See `struct pwrfip_node`.

    - varid_list:
      Pointer to a list of IDs (16-bit) to request.

    - varid_cnt:
      Number of IDs contained in the list.

    - channel:
      Channel used to make the request.
      See `enum pwrfip_var_aper_channel_type`.

  - OUT

    - ch_error:
      Channel error.
      See `enum pwrfip_var_err_code`.

Return Value

  If successful, `pwrfip_varidlist_aper_request()` returns 0.
  If unsuccessful, `pwrfip_varidlist_aper_request()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is not running. It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

Remarks

  There are two possible error levels for this operation:

  1. The error returned by the `pwrfip_varidlist_aper_request()` function is related to a context error inside the library, or a communication error with the coprocessor.
     This type of error is quite critical since it indicates a malfunction of the library.

  2. The `ch_error` value indicates a potential problem with the FIP channel inside the coprocessor, but doesn’t compromise the operation of the library.
     For example, if the request queue is full, use `pwrfip_var_aper_channel_purge()` to clear the contents of the saturated channel.

Example

    static struct pwrfip_var_cfg prod_var_cfg = {
        .type = PWRFIP_VAR_TYPE_PROD,
        .id = 0x3800,
        .prod.payload_bsz = 8,
        .prod.flags = \
            /* enable prod status */
            PWRFIP_VAR_FLAGS_REFRESH | \
            /* enable aper var request */
            PWRFIP_VAR_FLAGS_APER_VAR_REQ,
        .prod.refreshment_ustime = 80000, /* 80ms */
        .prod.evt_type = PWRFIP_EVT_TYPE_NONE,
        .pwrfip_var_handler = NULL,
    };
    static uint16_t ids[4] = {
        0x1000,
        0x1001,
        0x1100,
        0x1101,
    };

    int main(int argc, char *argv[])
    {
        int err = 0;
        struct pwrfip_node *node;
        struct pwrfip_aele *al;
        uint8_t channel_error = 0;

        /**
         * Node initialization
         */
        /*...*/

        /* create an aele context */
        al = pwrfip_aele_create(node);
        if (!al) {
            printf("aele creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* create a production variable which support aperiodic variable requests */
        /* note: this variable must be queried cyclically by the master node */
        prod_var = pwrfip_var_create(al, &prod_var_cfg);
        if (!prod_var) {
            printf("production variable creation failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* node startup (slave) */
        err = pwrfip_node_start(al, NULL, 0);
        if (err) {
            printf("node startup failed: %s\n", pwrfip_strerror(errno));
            err = -1;
            goto end;
        }

        /* main loop */
        for(;;) {
            /* request for an IDs list each 1 second */

            if (pwrfip_varidlist_aper_request(node, ids, 4,
                    PWRFIP_VAR_APER_CH_NORMAL, &channel_error)) {
                printf("var_aper_request failed: %s\n", pwrfip_strerror(errno));
                /* we consider this error as fatal error; so we
                 * stop the test */
                break;
            }

            /* check channel error */
            if (channel_error)
                printf("var_aper_request state error: %d\n", channel_error);

            sleep(1); /* 1s */
        }

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.7.6. varlist_aper_request

Description

  Sends an aperiodic request for a list of FIP variables.

| This function is similar to `pwrfip_varidlist_aper_request()` but use `struct pwrfip_var` objects instead of variable IDs (16-bit) in input parameter.

Prototype

    int pwrfip_varlist_aper_request(struct pwrfip_node *node,
                    struct pwrfip_var **var_list, int var_cnt,
                    enum pwrfip_var_aper_channel_type channel,
                    uint8_t *ch_error);

Parameters

  - IN

    - node:
      Pointer to the node that makes the request.
      See `struct pwrfip_node`.

    - var_list:
      Pointer to a list of variables to request.
      See `struct pwrfip_var`.

    - var_cnt:
      Number of variables contained in the list.

    - channel:
      Channel used to make the request.
      See `enum pwrfip_var_aper_channel_type`.

  - OUT

    - ch_error:
      Channel error.
      See `enum pwrfip_var_err_code`.

Return Value

  If successful, `pwrfip_varlist_aper_request()` returns 0.
  If unsuccessful, `pwrfip_varlist_aper_request()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is not running. It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.7.7. var_aper_channel_purge

Description

  Purges the target aperiodic variable channel.

Prototype

    int pwrfip_var_aper_channel_purge(struct pwrfip_node *node,
                    enum pwrfip_var_aper_channel_type channel,
                    uint16_t *purge_cnt, uint8_t *ch_error);

Parameters

  - IN

    - node:
      Pointer to the target node.
      See `struct pwrfip_node`.

    - channel:
      Channel to purge.
      See `enum pwrfip_var_aper_channel_type`.

  - OUT

    - purge_cnt:
      Number of variable IDs purged.

    - ch_error:
      Channel error.
      See `enum pwrfip_var_err_code`.

Return Value

  If successful, `pwrfip_var_aper_channel_purge()` returns 0.
  If unsuccessful, `pwrfip_var_aper_channel_purge()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameters.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is not running. It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

### 4.8. System Management Variables

#### 4.8.1. sm_ba_sync_get

Description

  Gets the BA synchronization information from the network (ID[0x9003]).

Prototype

    int pwrfip_sm_ba_sync_get(struct pwrfip_node *node,
                    struct pwrfip_sm_ba_sync *ba_sync)

Parameters

  - IN

    - node:
      Pointer to the target FIP node.
      See `struct pwrfip_node`.

  - OUT

    - ba_sync:
      BA synchronization structure to retrieve.
      See `struct pwrfip_sm_ba_sync`.

Return Value

  If successful, `pwrfip_sm_ba_sync_get()` returns 0.
  If unsuccessful, `pwrfip_sm_ba_sync_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is currently stopped.
    It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.8.2. sm_identification_get

Description

  Gets the identification information from a remote FIP node (ID[0x10XY] where XY is the remote address).

Prototype

    int pwrfip_sm_identification_get(struct pwrfip_node *node,
                    uint8_t node_addr, struct pwrfip_sm_identification *ident)

Parameters

  - IN

    - node:
      Pointer to the target FIP node (local node).
      See `struct pwrfip_node`.

    - node_addr:
      Remote node address to request.

  - OUT

    - ident:
      Identification structure to retrieve from the remote node.
      See `struct pwrfip_sm_identification`.

Return Value

  If successful, `pwrfip_sm_identification_get()` returns 0.
  If unsuccessful, `pwrfip_sm_identification_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is currently stopped.
    It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_AELE_VAR_NOT_FOUND:
    Unknown variable ID for this FIP node.
    Use `pwrfip_sm_var_create()` with the correct remote node address before using this function.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.8.3. sm_presence_get

Description

  Gets the presence information from a remote FIP node (ID[0x14XY] where XY is the remote address).

Prototype

    int pwrfip_sm_presence_get(struct pwrfip_node *node,
                    uint8_t node_addr, struct pwrfip_sm_presence *pres)

Parameters

  - IN

    - node:
      Pointer to the target FIP node (local node).
      See `struct pwrfip_node`.

    - node_addr:
      Remote node address to request.

  - OUT

    - pres:
      Presence structure to retrieve from the remote node.
      See `struct pwrfip_sm_presence`.

Return Value

  If successful, `pwrfip_sm_presence_get()` returns 0.
  If unsuccessful, `pwrfip_sm_presence_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is currently stopped.
    It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_AELE_VAR_NOT_FOUND:
    Unknown variable ID for this FIP node.
    Use `pwrfip_sm_var_create()` with the correct remote node address before using this function.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.8.4. sm_presence_list_get

Description

  Gets the presence list information from the network (ID[0x9002]).

Prototype

    int pwrfip_sm_presence_list_get(struct pwrfip_node *node,
                    struct pwrfip_sm_presence_list *pres_list)

Parameters

  - IN

    - node:
      Pointer to the target FIP node.
      See `struct pwrfip_node`.

  - OUT

    - pres_list:
      Presence list structure to retrieve.
      See `struct pwrfip_sm_presence_list`.

Return Value

  If successful, `pwrfip_sm_presence_list_get()` returns 0.
  If unsuccessful, `pwrfip_sm_presence_list_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is currently stopped.
    It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

#### 4.8.5. sm_report_get

Description

  Gets the report information from a remote FIP node (ID[0x11XY] where XY is the remote address).

Prototype

    int pwrfip_sm_report_get(struct pwrfip_node *node,
                    uint8_t node_addr, struct pwrfip_sm_report *report)

Parameters

  - IN

    - node:
      Pointer to the target FIP node (local node).
      See `struct pwrfip_node`.

    - node_addr:
      Remote node address to request.

  - OUT

    - report:
      Report structure to retrieve from the remote node.
      See `struct pwrfip_sm_report`.

Return Value

  If successful, `pwrfip_sm_report_get()` returns 0.
  If unsuccessful, `pwrfip_sm_report_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_AELE_NOT_RUN:
    FIP node is currently stopped.
    It is therefore impossible to query the coprocessor database.

  - PWRFIP_ERR_AELE_VAR_NOT_FOUND:
    Unknown variable ID for this FIP node.
    Use `pwrfip_sm_var_create()` with the correct remote node address before using this function.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

### 4.9. Medium

#### 4.9.1. medium_status_get

Description

  Get the status of the FIP channels.

Prototype

    int pwrfip_medium_status_get(struct pwrfip_node *node,
            struct pwrfip_medium_status *status)

Parameters

  - IN

    - node:
      Pointer to the target FIP node.
      See `struct pwrfip_node`.

  - OUT

    - status:
      Pointer to an output `struct pwrfip_medium_status`.

Return Value

  If successful, `pwrfip_medium_status_get()` returns 0.
  If unsuccessful, `pwrfip_medium_status_get()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input/output parameters.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

Example

    int main(int argc, char *argv[])
    {
        int err = 0;
        struct pwrfip_node *node;
        struct pwrfip_medium_status m_status;
        uint16_t m_state;

        /**
         * Node initialization
         */
        /*...*/

        /**
         * Node startup
         */
        /*...*/

        /* get medium state */
        err = pwrfip_medium_status_get(node, &m_status);
        if (err) {
            printf("medium status getter failed: %s\n", pwrfip_strerror(errno));
            goto end;
        }

        m_state = m_status.state;
        printf("medium_state  : 0x%04x\n", m_state);
        printf("  [channel 1]\n");
        printf("    enable    : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH1_VALID) ? "yes": "no");
        printf("    tx_err    : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH1_TX_ERROR) ? "yes": "no");
        printf("    watchdog  : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH1_WATCHDOG) ? "yes": "no");
        printf("  [channel 2]\n");
        printf("    enable    : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH2_VALID) ? "yes": "no");
        printf("    tx_err    : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH2_TX_ERROR) ? "yes": "no");
        printf("    watchdog  : %s\n",
            (m_state & PWRFIP_MEDIUM_STATE_CH2_WATCHDOG) ? "yes": "no");

        /**
         * Other tasks
         */
        /* ... */

    end:
        /**
         * Node exit
         */
        /*...*/
        return err;
    }

#### 4.9.2. medium_cmd_set

Description

  Sends a command to the coprocessor to control the FIP channels.
  The following operations are allowed for each channel:

  - Enable/Disable

  - Reset

  - Clear error

Prototype

    int pwrfip_medium_cmd_set(struct pwrfip_node *node, uint16_t flags)

Parameters

  - IN

    - node:
      Pointer to the target FIP node.
      See `struct pwrfip_node`.

    - flags:
      Command to send to the FIP channels manager.

| The available commands are described by the `enum pwrfip_medium_cmd_flag`.

- OUT - None

  Return Value

    If successful, `pwrfip_medium_cmd_set()` returns 0.
    If unsuccessful, `pwrfip_medium_cmd_set()` returns -1 and sets errno to one of the following values:

- EINVAL:
  Invalid input parameters.

- PWRFIP_ERR_COM_XXX:
  Communication error with the coprocessor.

### 4.10. Coprocessor Management Tasks

#### 4.10.1. its_process

Description

  Reads and processes all FIP asynchronous events notified by the coprocessor.

Prototype

    int pwrfip_its_process(struct pwrfip_node *node)

Parameters

  - IN

    - node:
      Pointer to the node to treat.
      See `struct pwrfip_node`.

  - OUT - None

Return Value

  If successful, `pwrfip_its_process()` returns 0.
  If unsuccessful, `pwrfip_its_process()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameter.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

Remarks

| Case of PCI/PCIe devices If a PCI/PCIe PowerFIP device is bound to the node (see `struct pwrfip_node_cfg`, `.dev` field), this function will be called automatically by an internal interrupt handler inside the library. In order to correctly raise the interrupt, the user must configure at least one synchronous event during the FIP periodic cycle: set-up a synchronization variable. (see `enum pwrfip_var_type` [PWRFIP_VAR_TYPE_SYNC]) set-up a prod/cons variable with a permanent event on request detection. (see `enum pwrfip_evt_type` [PWRFIP_EVT_TYPE_PERMANENT_ID]).

| User handlers called inside this function pwrfip_var_handler pwrfip_msg_recv_handler pwrfip_msg_send_handler pwrfip_urg_req_handler pwrfip_nor_req_handler pwrfip_ba_state_handler pwrfip_ba_sync_handler

#### 4.10.2. diag_process

Description

  Performs a local diagnosis of the node. This function reads the local node report,
  [i.e. `pwrfip_node_report_get()`], and updates the Report SM-MPS variable.

Prototype

    int pwrfip_diag_process(struct pwrfip_node *node)

Parameters

  - IN

    - node:
      Pointer to the node to treat.
      See `struct pwrfip_node`.

  - OUT - None

Return Value

  If successful, `pwrfip_diag_process()` returns 0.
  If unsuccessful, `pwrfip_diag_process()` returns -1 and sets errno to one of the following values:

  - EINVAL:
    Invalid input parameter.

  - PWRFIP_ERR_COM_XXX:
    Communication error with the coprocessor.

Remarks

| Case of PCI/PCIe devices If a PCI/PCIe PowerFIP device is bound to the node (see `struct pwrfip_node_cfg`, `.dev` field), this function will be called automatically by an internal thread inside the library.

| Case of PowerFIP-CC In order to update the Report - 0x11XY variable correctly, it is advisable to call this function at the correct frequency: @31.25Kbps: 1.6s @1Mbps: 500ms @2.5Mbps: 200ms @5Mbps: 100ms @12.5Mbps: 40ms @25Mbps: 20ms

| User handlers called inside this function pwrfip_error_handler

## 5. Structures

### 5.1. General

#### 5.1.1. date

Description

  Date structure.

Definition

    struct pwrfip_date {
        union {
            uint32_t raw;
            struct {
                uint8_t day;
                uint8_t month;
                uint8_t year;
                uint8_t reserved;
            } info;
        };
    };

Members

Name | Type | Description
--- | --- | ---
day | `uint8_t` | Day of the date.
month | `uint8_t` | Month of the date.
year | `uint8_t` | Year of the date.

#### 5.1.2. version

Description

  Version structure.

Definition

    struct pwrfip_version {
        union {
            uint32_t raw;
            struct {
                uint8_t patch;
                uint8_t minor;
                uint8_t major;
                uint8_t reserved;
            } info;
        };
        /* build date */
        struct pwrfip_date date;
    };

Members

Name | Type | Description
--- | --- | ---
patch | `uint8_t` | Patch version Marks bug fixes
minor | `uint8_t` | Minor version New features without break of compatibility
major | `uint8_t` | Major version Break of compatibility (ex: API changes)
date | `struct pwrfip_date` | Build date See `struct pwrfip_date`

### 5.2. Device

#### 5.2.1. dev_infos

Description

  System information about the PowerFIP board.

Definition

    struct pwrfip_dev_infos {
        uint32_t    index;
        uint64_t    fsn;
        /* device general info */
        uint16_t    vid;
        uint16_t    did;
        uint16_t    ssvid;
        uint16_t    ssdid;
        /* physical BAR addresses */
        int         bar_cnt;
        uint64_t    bar_bsz[BAR_MAX];
        uint64_t    bar_base[BAR_MAX];
        /* irq infos */
        int         irq_number;
        /* driver infos */
        uint32_t    drv_version;
        uint32_t    drv_date;
    };

Members

Name | Type | Description
--- | --- | ---
index | `uint32_t` | Device index
fsn | `uint64_t` | Factory Serial Number
vid | `uint16_t` | Vendor ID
did | `uint16_t` | Device ID
ssvid | `uint16_t` | Subsystem Vendor ID
ssdid | `uint16_t` | Subsystem Device ID
bar_cnt | `int` | Number of BAR (Base Address Register) for this device
bar_bsz | `uint64_t[BAR_MAX]` | Size of the BAR areas
bar_base | `uint64_t[BAR_MAX]` | Memory base start address for each area.
irq_number | `int` | IRQ number
drv_version | `uint32_t` | Driver version
drv_date | `uint32_t` | Driver built date

#### 5.2.2. dev_report

Description

  Global report of the PowerFIP board.

Definition

    struct pwrfip_dev_report {
        float temperature;
    };

Members

Name | Type | Description
--- | --- | ---
temperature | `float` | Temperature sensor (°C)

### 5.3. Configuration

#### 5.3.1. ba_request

Description

  Structure used to set-up an ID_DAT/ID_MSG request during a macrocycle periodic window.

Definition

    struct pwrfip_ba_request {
        enum pwrfip_ba_id_type type;
        uint16_t id;
    };

Members

Name | Type | Description
--- | --- | ---
type | `enum pwrfip_ba_id_type` | Frame control code for the request See `enum pwrfip_ba_id_type`
id | `uint16_t` | FIP identifier to request

#### 5.3.2. ba_aper_msg_wind_cfg

Description

  Structure used to set-up a macrocycle aperiodic message window.

Definition

    struct pwrfip_ba_aper_msg_wind_cfg {
        uint32_t end_ustime;
    };

Members

Name | Type | Description
--- | --- | ---
end_ustime | `uint32_t` | End of aperiodic message window in microseconds (relative to macrocycle start)

#### 5.3.3. ba_aper_var_wind_cfg

Description

  Structure used to set-up a macrocycle aperiodic variable window.

Definition

    struct pwrfip_ba_aper_var_wind_cfg {
        uint32_t end_ustime;
        int enable_testp;
    };

Members

Name | Type | Description
--- | --- | ---
end_ustime | `uint32_t` | End of aperiodic variable window in microseconds (relative to macrocycle start)
enable_testp | `int` | Enable the presence test if the bus arbiter doesn’t have other tasks to perform during this window

#### 5.3.4. ba_per_wind_cfg

Description

  Structure used to set-up a macrocycle periodic window.

Definition

    struct pwrfip_ba_per_wind_cfg {
        int req_cnt;
        struct pwrfip_ba_request *req_list;
    };

Members

Name | Type | Description
--- | --- | ---
req_cnt | `int` | Number of periodic request
req_list | `struct pwrfip_ba_request *` | List of periodic requests See `struct pwrfip_ba_request`

#### 5.3.5. ba_wait_wind_cfg

Description

  Structure used to set-up a macrocycle wait window.

Definition

    struct pwrfip_ba_wait_wind_cfg {
        uint32_t end_ustime;
        int is_silent;
        int is_ext_resync;
    };

Members

Name | Type | Description
--- | --- | ---
end_ustime | `uint32_t` | End of waiting window in microseconds (relative to the macrocycle start time)
is_silent | `int` | Waiting type 0: Padding frame emission 1: No frame during waiting
| In a context where several bus arbiter are waiting on the FIP network, it is not recommended to use the silent mode to avoid conflicts between potential masters
is_ext_resync | `int` | Resynchronization type 0: internal The coprocessor itself initiates the looping of the macrocycle. To do this, it uses its own internal timer 1: external The coprocessor listens to an external trigger before looping the macrocycle

#### 5.3.6. ba_wind_cfg

Description

  Structure used to set-up a macrocycle window for a master FIP node.

Definition

    struct pwrfip_ba_wind_cfg {
        enum pwrfip_ba_wind_type type;
        union {
            struct pwrfip_ba_per_wind_cfg per;
            struct pwrfip_ba_aper_var_wind_cfg aper_var;
            struct pwrfip_ba_aper_msg_wind_cfg aper_msg;
            struct pwrfip_ba_wait_wind_cfg wait;
        };
    };

Members

Name | Type | Description
--- | --- | ---
type | `enum pwrfip_ba_wind_type` | Macrocycle window type See `enum pwrfip_ba_wind_type`
per aper_var aper_msg wait | `union { struct pwrfip_ba_per_wind_cfg per; struct pwrfip_ba_aper_var_wind_cfg aper_var; struct pwrfip_ba_aper_msg_wind_cfg aper_msg; struct pwrfip_ba_wait_wind_cfg wait; }` | Specialized configuration structure according to the `.type` field of the macrocycle window See: `struct pwrfip_ba_per_wind_cfg` `struct pwrfip_ba_aper_var_wind_cfg` `struct pwrfip_ba_aper_msg_wind_cfg` `struct pwrfip_ba_wait_wind_cfg`

#### 5.3.7. ba_mcycle_cfg

Description

  Structure used to set-up a macrocycle for a master FIP node.

Definition

    struct pwrfip_ba_mcycle_cfg {
        int wind_cnt;
        struct pwrfip_ba_wind_cfg *wind_list;
    };

Members

Name | Type | Description
--- | --- | ---
wind_cnt | `int` | Number of macrocycle window configurations
req_list | `struct pwrfip_ba_wind_cfg *` | List of window configurations See `struct pwrfip_ba_wind_cfg`

#### 5.3.8. ba_startup_cfg

Description

  This structure is used to set start-up and election times of a master node (Bus Arbiter).

Definition

    struct pwrfip_ba_startup_cfg {
        enum pwrfip_ba_startup_mode mode;
        uint32_t silence_ustime;
        uint8_t max_phy_addr;
        uint8_t max_prio;
        uint8_t my_phy_addr;
        uint8_t my_prio;
    };

Members

Name | Type | Description
--- | --- | ---
mode | `enum pwrfip_ba_startup_mode` | Calculation method for bus arbiter startup and election times. See `enum pwrfip_ba_startup_mode`
silence_ustime | `uint32_t` | Silence time in microseconds.
max_phy_addr | `uint8_t` | Last FIP agent address with master capability on network.
max_prio | `uint8_t` | Highest BA priority on the network. Should be in [0..15] range.
| 0 is the highest priority.
my_phy_addr | `uint8_t` | Physical address of this BA.
my_prio | `uint8_t` | Priority of this BA. Should be in [0..15] range.
| 0 is the highest priority.

#### 5.3.9. msg_rx_cfg

Description

  Specific set-up structure for an incoming FIP message.

Definition

    struct pwrfip_msg_rx_cfg {
        uint16_t reserved;
    };

Members

Name | Type | Description
--- | --- | ---
reserved | `uint16_t` | Not significant field

#### 5.3.10. msg_tx_cfg

Description

  Specific set-up structure for an outcoming FIP message.

Definition

    struct pwrfip_msg_tx_cfg {
        uint8_t channel;
        uint8_t ack_mode;
    };

Members

Name | Type | Description
--- | --- | ---
channel | `uint8_t` | Message TX channel number. See `enum pwrfip_msg_tx_channel`
ack_mode | `uint8_t` | Message acknowledgement mode. See `enum pwrfip_msg_tx_ack_mode`

#### 5.3.11. msg_cfg

Description

  Generic set-up structure of a FIP message for a FIP node.

Definition

    struct pwrfip_msg_cfg {
        enum pwrfip_msg_type type;
        struct pwrfip_msg_hdr hdr;
        union {
            struct pwrfip_msg_tx_cfg tx;
            struct pwrfip_msg_rx_cfg rx;
        };
        void *user_ctx;
        void (* pwrfip_msg_handler)(struct pwrfip_node *node,
                struct pwrfip_msg *msg, struct pwrfip_event *evt);
    };

Members

Name | Type | Description
--- | --- | ---
type | `enum pwrfip_msg_type` | Message type (Transmission, Reception). See `enum pwrfip_msg_type`.
hdr | `struct pwrfip_msg_hdr` | Message header. See `struct pwrfip_msg_hdr`.
tx/rx | `union { struct pwrfip_msg_tx_cfg tx; struct pwrfip_msg_rx_cfg rx; }` | Specialized configuration structure according to the `.type` field of the message. See: `struct pwrfip_msg_tx_cfg` `struct pwrfip_msg_rx_cfg`
user_ctx | `void *` | User-specified context associated with this message. [Optional]
pwrfip_msg_handler | `void (* handler) ( struct pwrfip_node *node, struct pwrfip_msg *msg, struct pwrfip_event *evt )` | Local handler definition for a message.
| If `pwrfip_msg_handler=NULL`, the general handlers `pwrfip_msg_send_handler` or `pwrfip_msg_recv_handler` located in the `node_cfg` structure, will take over in case of an event.
| If neither - local or general - handler is set, the user will not be notified of the message events.
See: `struct pwrfip_node` `struct pwrfip_msg` `struct pwrfip_event`

#### 5.3.12. node_ba_cfg

Description

  Bus Arbiter configuration structure for a FIP node.

Definition

    struct pwrfip_node_ba_cfg {
        int enable;
        /**
         * => BA: StartUp/Election settings
         */
        uint32_t priority;
        uint32_t start_ustime;
        uint32_t election_ustime;
        /**
         * => BA: Aperiodic requests FIFOs settings
         */
        uint32_t msg_req_fifo_size;
        uint32_t urgent_var_req_fifo_size;
        uint32_t normal_var_req_fifo_size;
    };

Members

Name | Type | Description
--- | --- | ---
enable | `int` | Enable/Disable bus arbiter (master) capability. If disabled, all other structure members are non significant.
priority | `uint32_t` | Bus arbiter priority. Should be in [0..15] range.
| 0 is the highest priority.
start_ustime | `uint32_t` | Bus arbiter start-up time in microseconds.
| When the user calls the `pwrfip_ba_start()` function, the node initiates its bus arbiter start procedure with settings of the start-up timeout. Before the end of the start-up countdown, if an activity is detected on the network, the bus arbiter enter in idle mode and considers itself as potentially eligible. At the start-up timeout, having detected no activity on the network, the bus arbiter sends three padding identifiers on the line to check its ability to transmit. If faults are detected, the BA reports the anomaly to the user (event code: PWRFIP_EVT_BA_STOP_ERR) and switches to stopped status. Otherwise it enters idle status, and starts its election countdown.
election_ustime | `uint32_t` | Bus arbiter election time in microseconds.
| Several bus arbiters can be started on the FIP network, but only one is active at a time (the others are in idle mode). This time is set differently for each potential bus arbiter. When the active bus arbiter fails (no traffic on the line), the other arbiters start their election countdown. The first one to arrive at the end of the countdown becomes active (master) and the other nodes are put to idle mode.
msg_req_fifo_size | `uint32_t` | Bus arbiter queue size for aperiodic message requests. Should be in [1..128] range. If value is 0, it will be automatically set to default value (60).
urgent_var_req_fifo_size | `uint32_t` | Bus arbiter queue size for aperiodic variable requests (urgent priority). Should be in [1..128] range. If value is 0, it will be automatically set to default value (60).
normal_var_req_fifo_size | `uint32_t` | Bus arbiter queue size for aperiodic variable requests (normal priority). Should be in [1..128] range. If value is 0, it will be automatically set to default value (60).

#### 5.3.13. node_cfg

Description

  Node configuration structure.

Definition

    struct pwrfip_node_cfg {
        /**
         * General FIP settings
         */
        uint8_t fip_phy_addr;
        uint8_t fip_seg_num;
        uint8_t fip_frm_type;
        uint8_t fip_bitrate;
        uint32_t turn_around_ustime;
        uint32_t silence_ustime;
        uint32_t watchdog_ustime;
        /**
         * Extra FIP settings
         */
        int enable_bimedium;
        struct pwrfip_node_msg_cfg msg;
        struct pwrfip_node_ba_cfg ba;
        struct pwrfip_node_ident_cfg ident;
        struct pwrfip_node_prtcl_cfg prtcl_ext;
        /**
         * Hardware access
         */
        struct pwrfip_dev *dev;
        struct pwrfip_proc_cfg proc;
        /**
         * General Handlers
         */
        void *user_ctx;
        void (* pwrfip_var_handler)(
            struct pwrfip_node *node,
            struct pwrfip_var *var,
            struct pwrfip_event *evt);
        void (* pwrfip_msg_recv_handler)(
            struct pwrfip_node *node,
            struct pwrfip_msg *msg,
            struct pwrfip_event *evt);
        void (* pwrfip_msg_send_handler)(
            struct pwrfip_node *node,
            struct pwrfip_msg *msg,
            struct pwrfip_event *evt);
        void (* pwrfip_urg_req_handler)(
            struct pwrfip_node *node,
            struct pwrfip_event *evt);
        void (* pwrfip_nor_req_handler)(
            struct pwrfip_node *node,
            struct pwrfip_event *evt);
        void (* pwrfip_ba_state_handler)(
            struct pwrfip_node *node,
            struct pwrfip_event *evt);
        void (* pwrfip_ba_sync_handler)(
            struct pwrfip_node *node,
            struct pwrfip_var *var,
            struct pwrfip_event *evt);
        void (* pwrfip_error_handler)(
            struct pwrfip_node *node,
            enum pwrfip_error_code error);
        void (* pwrfip_reset_handler)(
            struct pwrfip_node *node);
    };

Members

Name | Type | Description
--- | --- | ---
fip_phy_addr | `uint8_t` | Physical address of the agent (node address)
fip_seg_num | `uint8_t` | FIP segment number to which the agent belongs
fip_frm_type | `uint8_t` | FIP frame type See `enum pwrfip_frame_type`
fip_bitrate | `uint8_t` | FIP bitrate See `enum pwrfip_bitrate`
turn_around_ustime | `uint32_t` | Turn-Around time in microseconds (0=default time)
| Time range according to bitrate 31.25Kbps min=320us max=8232us default=424us 1Mbps min=10us max=258us default=30us 2.5Mbps min=13us max=103us default=30us 5Mbps min=13us max=103us default=32us 12.5Mbps min=13us max=103us default=32us 25Mbps min=13us max=103us default=32us
silence_ustime | `uint32_t` | Silence time in microseconds (0=default time)
| Time range according to bitrate 31.25Kbps min=2880us max=65535us default=4096us 1Mbps min=70us max=65535us default=150us 2.5Mbps min=36us max=65535us default=96us 5Mbps min=36us max=65535us default=92us 12.5Mbps min=36us max=65535us default=92us 25Mbps min=36us max=65535us default=92us
watchdog_ustime | `uint32_t` | Watchdog time in us (0=disabled). Range is [0;42949672] us (i.e. max ~42s). The node (coprocessor) automatically disconnects from the FIP network if it is not requested frequently enough by the PowerFIP API (userapp). [Optional]
enable_bimedium | `int` | Enable/Disable Medium redundancy (eq. fieldual)
msg | `struct pwrfip_node_msg_cfg` | Messaging capability. [Optional] See `struct pwrfip_node_msg_cfg`
ba | `struct pwrfip_node_ba_cfg` | Master (Bus Arbiter) capability. [Optional] See `struct pwrfip_node_ba_cfg`
ident | `struct pwrfip_node_ident_cfg` | Node identification. The SM-MPS identification variable (0x10XY where XY is the node address) will be automatically created from this structure. [Mandatory] See `struct pwrfip_node_ident_cfg`
prtcl_ext | `struct pwrfip_node_prtcl_cfg` | Protocol extension capability. [Optional] See `struct pwrfip_node_prtcl_cfg`
dev | `struct pwrfip_dev *` | PCI/PCIe device to bind with node. Opaque structure created by the `pwrfip_device_open()` function.
proc | `struct pwrfip_proc_cfg` | Coprocessor configuration (chip access) See: `struct pwrfip_proc_cfg`
user_ctx | `void *` | User context pointer [Optional]
pwrfip_var_handler | `void (* handler) ( struct pwrfip_node *node, struct pwrfip_var *var, struct pwrfip_event *evt )` | General variable handler (Node Level) [Optional] See: `struct pwrfip_node` `struct pwrfip_var` `struct pwrfip_event`
pwrfip_msg_recv_handler | `void (* handler) ( struct pwrfip_node *node, struct pwrfip_msg *msg, struct pwrfip_event *evt )` | General message reception handler [Optional] See: `struct pwrfip_node` `struct pwrfip_msg` `struct pwrfip_event`
pwrfip_msg_send_handler | `void (* handler) ( struct pwrfip_node *node, struct pwrfip_msg *msg, struct pwrfip_event *evt )` | General message emission handler [Optional] See: `struct pwrfip_node` `struct pwrfip_msg` `struct pwrfip_event`
pwrfip_urg_req_handler | `void (* handler) ( struct pwrfip_node *node, struct pwrfip_event *evt )` | Urgent aperiodic variable transmission request handler [Optional] See: `struct pwrfip_node` `struct pwrfip_event`
pwrfip_nor_req_handler | `void (* handler) ( struct pwrfip_node *node, struct pwrfip_event *evt )` | Normal aperiodic variable transmission request handler [Optional] See: `struct pwrfip_node` `struct pwrfip_event`
pwrfip_ba_state_handler | `void (* handler) ( struct pwrfip_node *node, struct pwrfip_event *evt )` | Bus arbiter state event handler [Optional] See: `struct pwrfip_node` `struct pwrfip_event`
pwrfip_ba_sync_handler | `void (* handler) ( struct pwrfip_node *node, struct pwrfip_var *var, struct pwrfip_event *evt )` | Dedicated handler for the SM-MPS BA synchronization variable (0x9003). [Optional]
| It is usual to use this identifier as pure event to synchronize tasks between FIP nodes. By convention, the ID_DAT(0x9003) ends the macrocycle of the bus arbiter.
See: `struct pwrfip_node` `struct pwrfip_var` `struct pwrfip_event`
pwrfip_error_handler | `void (* handler) ( struct pwrfip_node *node, enum pwrfip_error_code error )` | Internal library error handler [Mandatory] See: `struct pwrfip_node` `enum pwrfip_error_code`
pwrfip_reset_handler | `void (* handler) ( struct pwrfip_node *node )` | Reset chip procedure handler [Mandatory] See `struct pwrfip_node`

Remarks

| Hardware access Two methods are provided to bind the FIP component with the library: Use the `.proc` field to manually configure the PowerFIP chip DPM (Dual-Port Memory) access. Use the `.dev` field to attach a PCI/PCIe device. Note: In this case no need to configure `.proc` field.

#### 5.3.14. node_ident_cfg

Description

  Identification configuration structure.
  This structure allows to create the SM-MPS identification variable in production for the local FIP node.
  (0x10XY where XY is node address).

Definition

    struct pwrfip_node_ident_cfg {
        char *manufacturer_name;
        char *model_name;
        uint8_t revision;
        char *tag_name;
        char *vendor_field;
    };

Members

Name | Type | Description
--- | --- | ---
manufacturer_name | `char*` | Vendor (or manufacturer) name in ASCII.
model_name | `char*` | Model name in ASCII.
revision | `uint8_t` | Revision number (ex: 0x23 [v2.3]).
tag_name | `char*` | Tag name. [Optional]
vendor_field | `char*` | Additional information. Free for the vendor. [Optional]

#### 5.3.15. node_msg_cfg

Description

  Messaging configuration structure for a FIP node.

Definition

    #define PWRFIP_MSG_TX_CH_PER_CNT 8

    struct pwrfip_node_msg_cfg {
        int enable;
        /**
         * => Reception settings
         */
        uint32_t rx_fifo_size;
        uint8_t rx_segment_tab[256];
        /**
         * => Emission settings
         */
        uint32_t tx_aper_fifo_size;
        uint32_t tx_per_fifo_size[PWRFIP_MSG_TX_CH_PER_CNT];
        uint16_t tx_per_fifo_id[PWRFIP_MSG_TX_CH_PER_CNT];
        uint8_t tx_max_repeat;
    };

Members

Name | Type | Description
--- | --- | ---
enable | `int` | Enable/Disable FIP messaging. If disabled, all other structure members are non significant.
rx_fifo_size | `uint32_t` | Consumption queues sizes for FIP messages min=1, max=64, default=30 (0: default value)
rx_segment_tab[256] | `uint8_t` | Sensitivity of the node for the message reception according to the segment destination. See `enum pwrfip_msg_rx_seg_cap`
tx_aper_fifo_size | `uint32_t` | Transmission queues sizes for FIP aperiodic messages. min=1, max=64; default=24 (0: default value)
tx_per_fifo_size[8] | `uint32_t` | Transmission queues sizes for FIP periodic messages (8 channels). min=1, max=64; default=24 (0: default value)
tx_per_fifo_id[8] | `uint16_t` | FIP identifier attached to the periodic message transmission queue (8 channels). 0: no ID attached, else: ID to query via ID_MSG frame
tx_max_repeat | `uint8_t` | Number of retries to send a message if no acknowledgement received.

#### 5.3.16. node_prtcl_cfg

Description

  Protocol extension configuration structure.

| Do not use this structure configuration if you want to keep the strict definition of the FIP/WorldFIP protocol (IEC 61158)

Definition

    struct pwrfip_node_prtcl_cfg {
        int enable;
        int enable_var_long_form;
    };

Members

Name | Type | Description
--- | --- | ---
enable | `int` | Enable/Disable protocol extension capability. If disabled, all other structure members are non significant.
enable_var_long_form | `int` | Extend FIP/WorldFIP variable length: up to 505 bytes on copper medium PDU(1B) + LEN(3B) + DATA(up to 501B) up to 1024 bytes on optical medium PDU(1B) + LEN(3B) + DATA(up to 1020B)
| This parameter changes the length encoding byte for RP_DAT frames ('long form' instead of 'short form') (ISO/IEC 8825-1 ASN.1 - BER)

#### 5.3.17. proc_cfg

Description

  Set-up structure for direct management of the coprocessor.

Definition

    struct pwrfip_proc_cfg {
        uint32_t base_addr;
        void *hnd;
        void (* pwrfip_ioread32)(void *hnd, uint32_t *addr, uint32_t *value);
        void (* pwrfip_iowrite32)(void *hnd, uint32_t *addr, uint32_t value);
    };

Members

Name | Type | Description
--- | --- | ---
base_addr | `uint32_t` | Start address offset of dual-port memory area.
hnd | `void *` | Context associated with the coprocessor. [Optional]
pwrfip_ioread32 | `void (* handler) ( void *hnd, uint32_t *addr, uint32_t *value )` | 32-bit coprocessor read handler.
pwrfip_iowrite32 | `void (* handler) ( void *hnd, uint32_t *addr, uint32_t value )` | 32-bit coprocessor write handler.

#### 5.3.18. var_cons_cfg

Description

  Specific set-up structure for a consumption FIP variable.

Definition

    struct pwrfip_var_cons_cfg {
        uint16_t payload_bsz;
        uint16_t flags;
        uint32_t promptness_ustime;
        uint32_t evt_type;
    };

Members

Name | Type | Description
--- | --- | ---
payload_bsz | `uint16_t` | User data payload in bytes
flags | `uint16_t` | Set-up flags for consumption. See `enum pwrfip_var_flags`
promptness_ustime | `uint32_t` | Promptness period in microseconds
evt_type | `uint32_t` | Set-up flags for event (Enable/Disable + Lifetime). See `enum pwrfip_evt_type`

#### 5.3.19. var_prod_cfg

Description

  Specific set-up structure for a production FIP variable.

Definition

    struct pwrfip_var_prod_cfg {
        uint16_t payload_bsz;
        uint16_t flags;
        uint32_t refreshment_ustime;
        uint32_t evt_type;
    };

Members

Name | Type | Description
--- | --- | ---
payload_bsz | `uint16_t` | User data payload in bytes
flags | `uint16_t` | Set-up flags for production. See `enum pwrfip_var_flags`
refreshment_ustime | `uint32_t` | Refresment period in microseconds
evt_type | `uint32_t` | Set-up flags for event (Enable/Disable + Lifetime). See `enum pwrfip_evt_type`

#### 5.3.20. var_sync_cfg

Description

  Specific set-up structure for a synchronization FIP variable.

Definition

    struct pwrfip_var_sync_cfg {
        uint32_t reserved[3];
    };

Members

Name | Type | Description
--- | --- | ---
reserved | `uint32_t[3]` | Unused parameters

Remarks

  A synchronization data has no user payload attached to it (no RP_DAT frame on network).
  Only a FIP identifier and a permanent event are set-up.
  When the ID_DAT frame associated with this FIP identifier is received - or produced (master) - by the node, an event is triggered and the user handler is executed.

#### 5.3.21. var_cfg

Description

  Generic set-up structure of a FIP variable for a FIP node.

Definition

    struct pwrfip_var_cfg {
        enum pwrfip_var_type type;
        uint16_t id;
        union {
            struct pwrfip_var_cons_cfg cons;
            struct pwrfip_var_prod_cfg prod;
            struct pwrfip_var_sync_cfg sync;
        };
        void *user_ctx;
        void (* pwrfip_var_handler) (
            struct pwrfip_node *node,
            struct pwrfip_var *var,
            struct pwrfip_event *evt
        );
    };

Members

Name | Type | Description
--- | --- | ---
type | `enum pwrfip_var_type` | Variable type (Production, Consumption or Synchronization) See `enum pwrfip_var_type`.
id | `uint16_t` | FIP identifier
cons/prod/sync | `union { struct pwrfip_var_cons_cfg cons; struct pwrfip_var_prod_cfg prod; struct pwrfip_var_sync_cfg sync; }` | Specialized configuration structure according to the `.type` field of the variable. See: `struct pwrfip_var_cons_cfg` `struct pwrfip_var_prod_cfg` `struct pwrfip_var_sync_cfg`
user_ctx | `void *` | User-specified context associated with this variable. [Optional]
pwrfip_var_handler | `void (* handler) ( struct pwrfip_node *node, struct pwrfip_var *var, struct pwrfip_event *evt )` | Local handler definition for a synchronization variable. Or, if `.evt_type` field is set, for a production/consumption variable.
| If `pwrfip_var_handler=NULL`, the general handler, with the same name and located in the `node_cfg` structure, will take over in case of an event.
| If neither - local or general - handler is set, the user will not be notified of the variable events.
See: `struct pwrfip_node` `struct pwrfip_var` `struct pwrfip_event`

### 5.4. Objects

#### 5.4.1. msg

Description

  FIP Message object.
  This is the handle structure to interact with a FIP message.

Definition

    struct pwrfip_msg {
        struct pwrfip_msg_hdr hdr;
        uint16_t bsz;
        uint8_t *buffer;
        uint64_t epoch;
        uint8_t channel_num;
        uint8_t error;
        void *user_ctx;
        void *priv;
    };

Members

Name | Type | Description
--- | --- | ---
hdr | `struct pwrfip_msg_hdr` | Message header. See `struct pwrfip_msg_hdr`
bsz | `uint16_t` | Useful message byte size (without header). Range = [1;256]
buffer | `uint8_t *` | Pointer to the useful message data.
epoch | `uint64_t` | RX/TX epoch info.
channel_num | `uint8_t` | RX/TX channel number. TX: See `enum pwrfip_msg_tx_channel` RX: Always 0
error | `uint8_t` | Error code for the read/write operation on the message (eq. msg_state). This report is generated directly by the coprocessor according to the state of the message in its local database. See `enum pwrfip_msg_err_code`
user_ctx | `void *` | User-specified context.
priv | `void *` | Pointer to a reserved opaque structure

#### 5.4.2. node

Description

  FIP Node object.
  This is the handle structure to interact with a FIP node.

Definition

    struct pwrfip_node {
        struct pwrfip_node_infos *infos;
        void *priv;
    };

Members

Name | Type | Description
--- | --- | ---
infos | `struct pwrfip_node_infos *` | Pointer to the FIP node information See `struct pwrfip_node_infos`
priv | `void *` | Pointer to a reserved opaque structure

#### 5.4.3. var

Description

  FIP Variable object.
  This is the handle structure to interact with a FIP variable.

Definition

    struct pwrfip_var {
        uint16_t id;
        uint16_t bsz;
        uint8_t *buffer;
        struct {
            uint32_t prod_ustime;
            uint32_t send_ustime;
            uint32_t cons_ustime;
        } time_info;
        uint8_t error;
        void *user_ctx;
        void *priv;
    };

Members

Name | Type | Description
--- | --- | ---
id | `uint16_t` | FIP identifier of the variable
bsz | `uint16_t` | Useful variable byte size
buffer | `uint8_t *` | Pointer to the useful variable data.
prod_ustime | `uint32_t` | Consumed variable case: These value is significant only for a variable configured with dynamic refreshment status (see `enum pwrfip_var_flags`). This time expressed in microseconds is recorded by the producer node in the last four variable data byte (just before the production status). It indicates the time difference between the moment of updating in the database (variable write) and the moment of effective production on the network by the remote node. Produced variable case: In the case of a produced variable, this information is local to the node. It indicates the time elapsed since the last write on the network and the new write in the local database (write variable).
send_ustime | `uint32_t` | Frame transmission time on the network in microseconds.
cons_ustime | `uint32_t` | Time in microseconds between last variable reception from the network and its reading from local database by user. (Only significant for consumed variables)
error | `uint8_t` | Error code for the read/write operation on the variable (eq. var_state). This report is generated directly by the coprocessor according to the state of the variable in its local database (freshness, promptness, etc). See `enum pwrfip_var_err_code`
user_ctx | `void *` | User-specified context.
priv | `void *` | Pointer to a reserved opaque structure

### 5.5. Infos/Status/Report

#### 5.5.1. ba_status

Description

  Bus Arbiter status of FIP coprocessor.

Definition

    struct pwrfip_ba_status {
        uint16_t state;
        uint16_t window;
        uint32_t index;
    };

Members

Name | Type | Description
--- | --- | ---
state | `uint16_t` | Bus arbiter state (FSM: Finite State Machine) See `enum pwrfip_ba_state`
window | `uint16_t` | Macrocycle window currently active See `enum pwrfip_ba_wind_type`
index | `uint32_t` | Macrocycle index currently active

#### 5.5.2. medium_status

Description

  Medium (Channels) status of FIP coprocessor.

Definition

    struct pwrfip_medium_status {
        uint16_t state;
        uint16_t reserved;
    };

Members

Name | Type | Description
--- | --- | ---
state | `uint16_t` | Medium state. See `enum pwrfip_medium_state`.
reserved | `uint16_t` | Reserved field.

#### 5.5.3. node_infos

Description

  Structure containing information about the FIP node (node configuration, software versions/dates).

Definition

    struct pwrfip_node_infos {
        struct pwrfip_node_cfg cfg;
        uint64_t cpu_id;
        uint32_t bss_bsz;
        uint32_t bss_max_bsz;
        struct pwrfip_version gw_version;
        struct pwrfip_version fw_version;
        struct pwrfip_version drv_version;
        struct pwrfip_version lib_version;
    };

Members

Name | Type | Description
--- | --- | ---
cfg | `struct pwrfip_node_cfg` | User configuration attached to the node See `struct pwrfip_node_cfg`
cpu_id | `uint64_t` | Coprocessor unique identifier
bss_bsz | `uint32_t` | Size in bytes of the node data contained in the BSS space of the coprocessor
bss_max_bsz | `uint32_t` | Maximum size in bytes of the coprocessor BSS space
gw_version | `struct pwrfip_version` | Coprocessor gateware version (FPGA) See `struct pwrfip_version`
fw_version | `struct pwrfip_version` | Coprocessor firmware version (C binary) powerfip-firmware.bin See `struct pwrfip_version`
drv_version | `struct pwrfip_version` | Driver version See `struct pwrfip_version`
lib_version | `struct pwrfip_version` | Library version See `struct pwrfip_version`

#### 5.5.4. node_report

Description

  Global report of the FIP coprocessor.

Definition

    struct pwrfip_node_report {
        struct pwrfip_node_status node_status;
        struct pwrfip_ba_status ba_status;
        struct pwrfip_medium_status medium_status;
        /* stats */
        struct pwrfip_tx_err tx_err;
        struct pwrfip_rx_err rx_err;
    };

Members

Name | Type | Description
--- | --- | ---
node_status | `struct pwrfip_node_status` | Node FSM and operation status See `struct pwrfip_node_status`
ba_status | `struct pwrfip_ba_status` | Bus arbiter FSM and window status See `struct pwrfip_ba_status`
medium_status | `struct pwrfip_medium_status` | Medium (Channels) Status See `struct pwrfip_medium_status`
tx_err | `struct pwrfip_tx_err` | Transmission errors statistics See `struct pwrfip_tx_err`
rx_err | `struct pwrfip_rx_err` | Reception errors statistics See `struct pwrfip_rx_err`

#### 5.5.5. node_status

Description

  General status of FIP node.

Definition

    struct pwrfip_node_status {
        uint16_t state;
        uint16_t op;
        int16_t  temperature;
        uint16_t reserved;
    };

Members

Name | Type | Description
--- | --- | ---
state | `uint16_t` | Node state (FSM: Finite State Machine) See `enum pwrfip_node_state`
op | `uint16_t` | Operation currently in progress See `enum pwrfip_node_operation`
temperature | `int16_t` | Chip temperature (2’s complement format)
reserved | `uint16_t` | Internal data (not documented)

#### 5.5.6. rx_err

Description

  Report of RX error by the coprocessor.

Definition

    struct pwrfip_rx_err {
        /**
         * MAU frame errors
         */
        /* no mau rx error occurs */
        uint64_t ok;
        /* -> Physical Layer errors */
        uint64_t pre_mis;
        uint64_t fsd_mis;
        uint64_t fsd_unk;
        uint64_t fed_mis;
        /* -> Data-Link Layer errors */
        uint64_t crc_bad;
        uint64_t reserved[10];
        /**
         * Application layer errors
         */
        uint64_t pdu_bad;
        uint64_t len_bad;
        uint64_t not_fresh;
        uint64_t not_prompt;
    };

Members

Name | Type | Description
--- | --- | ---
ok | `uint64_t` | Frame Ok. No MAU TX error occurs
pre_mis | `uint64_t` | Missing preamble (glitches on line)
fsd_mis | `uint64_t` | Missing Frame Start Delimiter (FSD)
fsd_unk | `uint64_t` | Unknown Frame Start Delimiter (FSD)
fed_mis | `uint64_t` | Missing Frame End Delimiter (FED)
crc_bad | `uint64_t` | Wrong Cyclic Redundancy Check (CRC)
reserved | `uint64_t[10]` | Internal errors (not documented)
pdu_bad | `uint64_t` | Unknown FIP Protocol Data Unit (PDU)
len_bad | `uint64_t` | Bad FIP frame length (LEN)
not_fresh | `uint64_t` | Consumed variable has not been correctly refreshed by a remote fip node (agent)
not_prompt | `uint64_t` | Consumed variable is not prompt. Local database hasn’t been read (by the user) during promptness period

#### 5.5.7. tx_err

Description

  Report of TX error by the coprocessor.

Definition

    struct pwrfip_tx_err {
        /**
         * Medium Attachment Unit (MAU) errors
         */
        uint64_t ok;
        uint64_t collision;
        uint64_t consistency;
        uint64_t reserved[5];
        /**
         * Application layer errors
         */
        uint64_t not_fresh;
    };

Members

Name | Type | Description
--- | --- | ---
ok | `uint64_t` | Frame Ok. No MAU TX error occurs
collision | `uint64_t` | Other frame present on network during transmission
consistency | `uint64_t` | The coprocessor listens to the FIP line at the time of its own transmission. This counter is incremented if a consistency problem is detected between the data sent and the data read back
reserved | `uint64_t[5]` | Internal errors (not documented)
not_fresh | `uint64_t` | Produced variable is not correctly refreshed inside local database (refreshment period has expired)

#### 5.5.8. sm_ba_sync

Description

  This structure allows to retrieve the BA synchronization SM-MPS variable (0x9003) from network.
  For more information about this variable, see this `appendix`.

Definition

    struct pwrfip_sm_ba_sync {
        uint8_t addr;
        uint8_t mcycle_num;
        struct pwrfip_var *var;
    };

Members

Name | Type | Description
--- | --- | ---
addr | `uint8_t` | Master node address (Bus Arbiter).
mcycle_num | `uint8_t` | Macrocycle number in progress.
var | `struct pwrfip_var *` | pointer to 0x9003 SM-MPS variable.

#### 5.5.9. sm_identification

Description

  This structure allows to retrieve an identification SM-MPS variable (0x10XY) from network.
  For more information about this variable, see this `appendix`.

Definition

    struct pwrfip_sm_identification {
        char manufacturer_name[128];
        char model_name[128];
        uint8_t revision;
        char tag_name[128];
        uint8_t smmps_class;
        char vendor_field[128];
        struct pwrfip_var *var;
    };

Members

Name | Type | Description
--- | --- | ---
manufacturer_name | `char[128]` | Vendor (or manufacturer) name in ASCII.
model_name | `char[128]` | Model name in ASCII.
revision | `uint8_t` | Revision number (ex: 0x23 [v2.3]).
tag_name | `char[128]` | Tag name.
smmps_class | `uint8_t` | SM-MPS conformity class.
vendor_field | `char[128]` | Additional information of the vendor.
var | `struct pwrfip_var *` | pointer to 0x10XY SM-MPS variable.

#### 5.5.10. sm_presence

Description

  This structure allows to retrieve a presence SM-MPS variable (0x14XY) from network.
  For more information about this variable, see this `appendix`.

Definition

    struct pwrfip_sm_presence {
        uint8_t ident_len;
        uint8_t ba_state;
        uint8_t ba_prio;
        struct pwrfip_var *var;
    };

Members

Name | Type | Description
--- | --- | ---
ident_len | `uint8_t` | Length of the SM-MPS identification variable related to this node.
ba_state | `uint8_t` | Bus arbiter state. See `enum pwrfip_ba_state`
ba_prio | `uint8_t` | BA priority of the node (if master supported). Within the range [0..15] (0: higher)
var | `struct pwrfip_var *` | pointer to 0x14XY SM-MPS variable.

#### 5.5.11. sm_presence_list

Description

  This structure allows to retrieve the presence list SM-MPS variable (0x9002) from network.
  For more information about this variable, see this `appendix`.

Definition

    struct pwrfip_sm_presence_list {
        int count;
        uint8_t addr[256];
        struct pwrfip_var *var;
    };

Members

Name | Type | Description
--- | --- | ---
count | `int` | Count of present FIP nodes on network.
addr | `uint8_t[256]` | Adresses table of present FIP nodes.
var | `struct pwrfip_var *` | pointer to 0x9002 SM-MPS variable.

#### 5.5.12. sm_report

Description

  This structure allows to retrieve a report SM-MPS variable (0x11XY) from network.
  For more information about this variable, see this `appendix`.

Definition

    union pwrfip_sm_report_ch_status {
        uint16_t value;
        struct {
            uint16_t tx_quality_ch1:1;
            uint16_t tx_quality_ch2:1;
            uint16_t rx_quality_ch1:1;
            uint16_t rx_quality_ch2:1;
            uint16_t valid_ch1:1;
            uint16_t valid_ch2:1;
            uint16_t traffic_ch1:1;
            uint16_t traffic_ch2:1;
            uint16_t summary_ch1:1;
            uint16_t summary_ch2:1;
            uint16_t reserved:6;
        };
    };

    struct pwrfip_sm_report {
        uint16_t rx_ok_ch1;
        uint16_t rx_ok_ch2;
        uint16_t rx_nok_ch1;
        uint16_t rx_nok_ch2;
        union pwrfip_sm_report_ch_status channel_status;
        struct pwrfip_var *var;
    };

Members

Name | Type | Description
--- | --- | ---
rx_ok_ch1 | `uint16_t` | Frames correctly received on channel 1 by time unit.
rx_ok_ch2 | `uint16_t` | Frames correctly received on channel 2 by time unit.
rx_nok_ch1 | `uint16_t` | Frames incorrectly received on channel 1 by time unit.
rx_nok_ch2 | `uint16_t` | Frames incorrectly received on channel 2 by time unit.
channel_status | `union pwrfip_sm_report_ch_status` | Medium status of the node.
var | `struct pwrfip_var *` | pointer to 0x11XY SM-MPS variable.

### 5.6. Extras

#### 5.6.1. event

Description

  FIP event.

Definition

    struct pwrfip_event {
        uint64_t epoch;
        uint16_t code;
        uint16_t param;
        uint32_t reserved[2];
    };

Members

Name | Type | Description
--- | --- | ---
epoch | `uint64_t` | Event epoch (10ns)
code | `uint16_t` | Event Code See `enum pwrfip_event_code`
param | `uint16_t` | Event Parameter. This parameter is significant only for some event codes. For more information, see `enum pwrfip_event_code`.
reserved | `uint32_t[2]` | Not documented fields

#### 5.6.2. msg_addr

Description

  FIP message address.

Definition

    struct pwrfip_msg_addr {
        union {
            uint32_t addr;
            struct {
                union {
                    uint8_t seg;
                    struct {
                        uint8_t seg_num:7;
                        uint8_t seg_group:1;
                    };
                };
                union {
                    uint16_t lsap;
                    struct {
                        uint16_t lsap_num:15;
                        uint16_t lsap_group:1;
                    };
                };
                uint8_t reserved;
            };
        };
    };

Members

Name | Type | Description
--- | --- | ---
addr | `uint32_t` | Data Link Layer (DLL) address
seg | `uint8_t` | FIP Segment field
seg_num | `uint8_t:7` | FIP Segment number
seg_group | `uint8_t:1` | Segment group: 0: Individual segment 1: Group segment
lsap | `uint16_t` | Link Service Access Point (LSAP)
lsap_num | `uint16_t:15` | LSAP number
lsap_group | `uint16_t:1` | LSAP group: 0: Individual address 1: Group address
reserved | `uint8_t` | Reserved field

#### 5.6.3. msg_hdr

Description

  FIP Message header.

Definition

    struct pwrfip_msg_hdr {
        struct pwrfip_msg_addr src;
        struct pwrfip_msg_addr dst;
    };

Members

Name | Type | Description
--- | --- | ---
src | `struct pwrfip_msg_addr` | Message source address. See `struct pwrfip_msg_addr`
dst | `struct pwrfip_msg_addr` | Message destination address. See `struct pwrfip_msg_addr`

## 6. Enumerations

### 6.1. ba_id_type

Description

  ID request type allowed inside a macrocycle periodic window (for a master node only).

Definition

    enum pwrfip_ba_id_type {
        PWRFIP_BA_ID_DAT = 0x03,
        PWRFIP_BA_ID_MSG = 0x05,
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_BA_ID_DAT | 0x03 | Bus arbiter request for a FIP variable.
PWRFIP_BA_ID_MSG | 0x05 | Bus arbiter request for a FIP message.

### 6.2. ba_startup_mode

Description

  Start-up mode of the bus arbiter.
  In a context where several bus arbiters are competing on the network to become master, it is necessary to give election priorities for each of them.
  This enumeration defines these calculation methods (or mode) allowing to set-up the start-up/election times of the bus arbiter according to the characteristics of the FIP node.

| Bus Arbiter 's Start-up and Election times BA_StartUp_Time (microseconds) = T0 x BA_StartUp_Par BA_Election_Time (microseconds) = T0 x BA_Election_Par Where T0 is the Silence Time in microseconds.

Definition

    enum pwrfip_ba_startup_mode {
        PWRFIP_BA_STUP_STANDARD,
        PWRFIP_BA_STUP_OPTIMIZE_1,
        PWRFIP_BA_STUP_OPTIMIZE_2,
        PWRFIP_BA_STUP_OPTIMIZE_3,
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_BA_STUP_STANDARD | 0 | BA_StartUp_Par = 8712 BA_Election_Par = 2 x [256 x (BA_Priority + 1) + Node_Phy_Addr + 3]
PWRFIP_BA_STUP_OPTIMIZE_1 | 1 | BA_StartUp_Par = 2 x [(BA_Max_Phy_Addr + 1) x 16 + 257 + 3] BA_Election_Par = 2 x [(BA_Max_Phy_Addr + 1) x (BA_Priority + 1) + Node_Phy_Addr + 3]
PWRFIP_BA_STUP_OPTIMIZE_2 | 2 | BA_StartUp_Par = 2 x [(BA_Max_Phy_Addr + 1) x (BA_Max_Priority + 1) + 257 + 3] BA_Election_Par = 2 x [(BA_Max_Phy_Addr + 1) x (BA_Priority + 1) + Node_Phy_Addr + 3]
PWRFIP_BA_STUP_OPTIMIZE_3 | 3 | BA_StartUp_Par = 2 x [(BA_Max_Phy_Addr + 1) x (BA_Max_Priority + 1) + 3] BA_Election_Par = 2 x [(BA_Max_Phy_Addr + 1) x (BA_Priority + 1) + Node_Phy_Addr + 3]
| Only for mono-medium topology.

Remarks

  These times can be automatically calculated with `pwrfip_ba_startup_calculate()` function.

### 6.3. ba_state

Description

  State of the bus arbiter.

Definition

    enum pwrfip_ba_state {
        PWRFIP_BA_STATE_INITIAL,
        PWRFIP_BA_STATE_READY,
        PWRFIP_BA_STATE_STARTING,
        PWRFIP_BA_STATE_IDLE,
        PWRFIP_BA_STATE_RUNNING,
        _PWRFIP_BA_STATE_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_BA_STATE_INITIAL | 0 | Initial state. No bus arbiter config loaded
PWRFIP_BA_STATE_READY | 1 | User macrocycles context loaded. Here, FIP node is in stopped state, and is ready to start.
PWRFIP_BA_STATE_STARTING | 2 | Starting-up state (not yet active). The bus arbiter is inside start-up procedure.
PWRFIP_BA_STATE_IDLE | 3 | Idle state (maybe another bus arbiter is active on network)
PWRFIP_BA_STATE_RUNNING | 4 | Running state. Current node is master. Bus arbiter is active on network
_PWRFIP_BA_STATE_MAX | 5 | Max BA state number

### 6.4. ba_wind_type

Description

  Type of macrocycle window.

Definition

    enum pwrfip_ba_wind_type {
        _PWRFIP_BA_WIND_TYPE_NONE,
        _PWRFIP_BA_WIND_TYPE_MIN,
        PWRFIP_BA_WIND_PER = _PWRFIP_BA_WIND_TYPE_MIN,
        PWRFIP_BA_WIND_APER_VAR,
        PWRFIP_BA_WIND_APER_MSG,
        PWRFIP_BA_WIND_WAIT,
        _PWRFIP_BA_WIND_TYPE_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_BA_WIND_TYPE_NONE | 0 | Invalid BA window type
_PWRFIP_BA_WIND_TYPE_MIN | 1 | Minimal valid type for a bus arbiter window
PWRFIP_BA_WIND_PER | 1 | Periodic window
PWRFIP_BA_WIND_APER_VAR | 2 | Aperiodic variable window
PWRFIP_BA_WIND_APER_MSG | 3 | Aperiodic message window
PWRFIP_BA_WIND_WAIT | 4 | External/Internal resync waiting window
_PWRFIP_BA_WIND_TYPE_MAX | 5 | Maximal valid type for a bus arbiter window

### 6.5. bitrate

Description

  FIP bitrate.

Definition

    enum pwrfip_bitrate {
        _PWRFIP_BITRATE_MIN = 1,
        PWRFIP_BITRATE_31K25 = _PWRFIP_BITRATE_MIN,
        PWRFIP_BITRATE_1M,
        PWRFIP_BITRATE_2M5,
        PWRFIP_BITRATE_5M,
        PWRFIP_BITRATE_12M5,
        PWRFIP_BITRATE_25M,
        _PWRFIP_BITRATE_MAX,
        _PWRFIP_BITRATE_UNKNOWN = 0,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_BITRATE_MIN | 1 | Minimum valid enum code for bitrate.
PWRFIP_BITRATE_31K25 | 1 | FIP/WorldFIP bitrate at 31.25Kbps.
PWRFIP_BITRATE_1M | 2 | FIP/WorldFIP bitrate at 1Mbps.
PWRFIP_BITRATE_2M5 | 3 | FIP/WorldFIP bitrate at 2.5Mbps.
PWRFIP_BITRATE_5M | 4 | FIP/WorldFIP bitrate at 5Mbps.
PWRFIP_BITRATE_12M5 | 5 | FIP/WorldFIP bitrate at 12.5Mbps.
PWRFIP_BITRATE_25M | 6 | FIP/WorldFIP bitrate at 25Mbps.
_PWRFIP_BITRATE_MAX | 7 | Maximum enum code for bitrate.
_PWRFIP_BITRATE_UNKNOWN | 0 | Not supported or unknown FIP bitrate.

### 6.6. error_code

Description

  Library and coprocessor communication error codes.

Definition

    enum pwrfip_error_code {
        _PWRFIP_ERR_CODE_MIN = 256,
        /* library error codes */
        PWRFIP_ERR_DEV_ALREADY_BIND = _PWRFIP_ERR_CODE_MIN,
        PWRFIP_ERR_DEV_IRQ_HANDLER_STARTED,
        PWRFIP_ERR_DEV_IRQ_HANDLER_STOPPED,
        PWRFIP_ERR_DEV_DIAG_TASK_STARTED,
        PWRFIP_ERR_DEV_DIAG_TASK_STOPPED,
        PWRFIP_ERR_AELE_NOT_STOP,
        PWRFIP_ERR_AELE_NOT_RUN,
        PWRFIP_ERR_AELE_VAR_NOT_FOUND,
        PWRFIP_ERR_BA_NOT_STOP,
        PWRFIP_ERR_BA_NOT_RUN,
        PWRFIP_ERR_INVALID_CTX,
        PWRFIP_ERR_CFG_VAR_TYPE_UNKNOWN,
        PWRFIP_ERR_CFG_VAR_DIR,
        PWRFIP_ERR_CFG_MSG_PROD,
        PWRFIP_ERR_CFG_MSG_DIR,
        PWRFIP_ERR_CFG_VAR_EXIST,
        PWRFIP_ERR_CFG_MSG_EXIST,
        PWRFIP_ERR_CFG_VAR_BAD_LEN,
        PWRFIP_ERR_CFG_MSG_TYPE_UNKNOWN,
        PWRFIP_ERR_CFG_MSG_TX_ACK_MODE_UNKNOWN,
        PWRFIP_ERR_CFG_MSG_TX_CH_PER_EXIST,
        PWRFIP_ERR_CFG_MSG_TX_CH_PER_UNKNOWN,
        PWRFIP_ERR_CFG_MSG_TX_CH_PER_NOID,
        PWRFIP_ERR_MCYCLE_WIND_COUNT,
        PWRFIP_ERR_MCYCLE_WIND_UNKNOWN,
        PWRFIP_ERR_MCYCLE_WIND_END,
        PWRFIP_ERR_MCYCLE_PER_WIND_REQ_COUNT,
        PWRFIP_ERR_MCYCLE_PER_WIND_REQ_UNKNOWN,
        PWRFIP_ERR_MCYCLE_WIND_TIME_INC,
        PWRFIP_ERR_NODE_BSS_OVERFLOW,
        PWRFIP_ERR_NODE_HANDLER_MISSING,
        PWRFIP_ERR_NODE_FRM_TYPE_INVALID,
        PWRFIP_ERR_NODE_BITRATE_INVALID,
        PWRFIP_ERR_NODE_MSG_CAP_NOT_SUPPORTED,
        PWRFIP_ERR_NODE_RX_MSG_FIFO_SZ,
        PWRFIP_ERR_NODE_RX_MSG_SEG_CAP,
        PWRFIP_ERR_NODE_TX_MSG_FIFO_SZ,
        PWRFIP_ERR_NODE_TX_MSG_REPEAT,
        PWRFIP_ERR_NODE_BA_STUP_TIMES,
        PWRFIP_ERR_NODE_BA_REQ_FIFO_SZ,
        PWRFIP_ERR_NODE_TR_INVALID,
        PWRFIP_ERR_NODE_TS_INVALID,
        PWRFIP_ERR_NODE_IDENT_PARAM,
        PWRFIP_ERR_NODE_IDENT_LEN,
        PWRFIP_ERR_BA_STUP_TS_INVALID,
        PWRFIP_ERR_BA_STUP_PHY_ADDR_INVALID,
        PWRFIP_ERR_BA_STUP_PRIO_INVALID,
        /* communication errors codes (mailboxes) */
        _PWRFIP_ERR_COM_CODE_OFFSET,
        PWRFIP_ERR_COM_DIR_UNKNOWN = _PWRFIP_ERR_COM_CODE_OFFSET,
        PWRFIP_ERR_COM_NOT_OUTBOX,
        PWRFIP_ERR_COM_NOT_INBOX,
        PWRFIP_ERR_COM_INVAL,
        PWRFIP_ERR_COM_TMO,
        PWRFIP_ERR_COM_BUSY,
        PWRFIP_ERR_COM_NO_PKT,
        PWRFIP_ERR_COM_PKT_BAD_SZ,
        PWRFIP_ERR_COM_PKT_BAD_CMD,
        PWRFIP_ERR_COM_PKT_RES_FAILED,
        PWRFIP_ERR_COM_DMA_BAD_OP,
        _PWRFIP_ERR_CODE_MAX,
    };

Values

Constant | Description
--- | ---
PWRFIP_ERR_DEV_ALREADY_BIND | The device is already bound to another FIP node session.
PWRFIP_ERR_DEV_IRQ_HANDLER_STARTED | IRQ handler is already started.
PWRFIP_ERR_DEV_IRQ_HANDLER_STOPPED | IRQ handler is already stopped.
PWRFIP_ERR_DEV_DIAG_TASK_STARTED | Diagnostic task is already started.
PWRFIP_ERR_DEV_DIAG_TASK_STOPPED | Diagnostic task is already stopped.
PWRFIP_ERR_AELE_NOT_STOP | FIP node is currently running.
PWRFIP_ERR_AELE_NOT_RUN | FIP node is currently stopped.
PWRFIP_ERR_AELE_VAR_NOT_FOUND | Unknown variable ID for this FIP node.
PWRFIP_ERR_BA_NOT_STOP | Macrocycle (BA) is not stopped.
PWRFIP_ERR_BA_NOT_RUN | No BA is currently running.
PWRFIP_ERR_INVALID_CTX | Objects (aele, mcycle…​) do not belong to the same node context.
PWRFIP_ERR_CFG_VAR_TYPE_UNKNOWN | Unknown variable type.
PWRFIP_ERR_CFG_VAR_DIR | Impossible to change the direction of the variable (prod/cons) for this ID.
PWRFIP_ERR_CFG_MSG_PROD | Impossible to link a produced message on this ID. A consumed variable is already attached to it.
PWRFIP_ERR_CFG_MSG_DIR | Impossible to change direction. A produced message is already attached to it.
PWRFIP_ERR_CFG_VAR_EXIST | A variable already exists for this ID.
PWRFIP_ERR_CFG_MSG_EXIST | A message already exists with this header.
PWRFIP_ERR_CFG_VAR_BAD_LEN | Incorrect payload size configuration.
| Maximum size: 126: variable without MPS status 125: variable with MPS status (refreshment) 121: variable with dynamic refreshment
PWRFIP_ERR_CFG_MSG_TYPE_UNKNOWN | Unknown message type.
PWRFIP_ERR_CFG_MSG_TX_ACK_MODE_UNKNOWN | Unknown message acknowledgement mode.
PWRFIP_ERR_CFG_MSG_TX_CH_PER_EXIST | A periodic message channel is already attached to this ID.
PWRFIP_ERR_CFG_MSG_TX_CH_PER_UNKNOWN | Unknown periodic message channel number.
PWRFIP_ERR_CFG_MSG_TX_CH_PER_NOID | No ID attached to this periodic message channel number.
PWRFIP_ERR_MCYCLE_WIND_COUNT | Invalid macrocycle windows count (should be at least 1).
PWRFIP_ERR_MCYCLE_WIND_UNKNOWN | Unknown macrocycle windows type.
PWRFIP_ERR_MCYCLE_WIND_END | Invalid macrocycle (should end with a WAIT window).
PWRFIP_ERR_MCYCLE_PER_WIND_REQ_COUNT | At least one request is required for BA periodic window.
PWRFIP_ERR_MCYCLE_PER_WIND_REQ_UNKNOWN | Unknown macrocycle periodic request (ID_DAT or ID_MSG).
PWRFIP_ERR_MCYCLE_WIND_TIME_INC | Overlap on macrocycle windows end times.
PWRFIP_ERR_NODE_BSS_OVERFLOW | BSS overflow. Queues size of the node should be reduced.
PWRFIP_ERR_NODE_HANDLER_MISSING | Reset/Error/Warning handlers are mandatory.
PWRFIP_ERR_NODE_FRM_TYPE_INVALID | Invalid frame type (FIP or WorldFIP).
PWRFIP_ERR_NODE_BITRATE_INVALID | Invalid node bitrate configuration.
PWRFIP_ERR_NODE_MSG_CAP_NOT_SUPPORTED | The node does not support messaging capability.
PWRFIP_ERR_NODE_RX_MSG_FIFO_SZ | Queue size for message consumption should be in [1..64] range.
PWRFIP_ERR_NODE_RX_MSG_SEG_CAP | Segment capability for consumption message should be [0..2].
PWRFIP_ERR_NODE_TX_MSG_FIFO_SZ | Queue size for message transmission should be in [1..64] range.
PWRFIP_ERR_NODE_TX_MSG_REPEAT | Maximum repeats for acknowledged message transmission should be in [0..3] range.
PWRFIP_ERR_NODE_BA_STUP_TIMES | The election time must be shorter than the start-up time.
PWRFIP_ERR_NODE_BA_REQ_FIFO_SZ | Queue size for BA requests should be in [1..64] range.
PWRFIP_ERR_NODE_TR_INVALID | Invalid FIP turn around time configuration.
PWRFIP_ERR_NODE_TS_INVALID | Invalid FIP silence time configuration.
PWRFIP_ERR_NODE_IDENT_PARAM | Mandatory parameters are missing for the node identification.
PWRFIP_ERR_NODE_IDENT_LEN | Node identification parameters exceed limit size.
PWRFIP_ERR_BA_STUP_TS_INVALID | Silence time should not be 0.
PWRFIP_ERR_BA_STUP_PHY_ADDR_INVALID | Local physical address should not exceed maximum network address.
PWRFIP_ERR_BA_STUP_PRIO_INVALID | Local BA priority should not exceed max priority (0: highest prio).
PWRFIP_ERR_COM_DIR_UNKNOW | Unknown direction for the mailbox.
PWRFIP_ERR_COM_NOT_OUTBOX | The mailbox is not configured as output.
PWRFIP_ERR_COM_NOT_INBOX | The mailbox is not configured as input.
PWRFIP_ERR_COM_INVAL | Mailbox invalid argument.
PWRFIP_ERR_COM_TMO | Mailbox timeout.
PWRFIP_ERR_COM_BUSY | Mailbox is busy.
PWRFIP_ERR_COM_NO_PKT | Mailbox has no packet to treat.
PWRFIP_ERR_COM_PKT_BAD_SZ | Incorrect packet size for the mailbox.
PWRFIP_ERR_COM_PKT_BAD_CMD | Unknown packet command id for the mailbox.
PWRFIP_ERR_COM_PKT_RES_FAILED | Error during response procedure (inbox).
PWRFIP_ERR_COM_DMA_BAD_OP | Bad DMA operation for mailbox.

### 6.7. event_code

Description

  FIP event codes of the library.

Definition

    enum pwrfip_event_code {
        PWRFIP_EVT_SEND_VAR_P = 0x8100,
        PWRFIP_EVT_SEND_VAR_T = 0x0100,
        PWRFIP_EVT_RECV_VAR_P = 0x8200,
        PWRFIP_EVT_RECV_VAR_T = 0x0200,
        PWRFIP_EVT_RECV_MSG = 0x0240,
        PWRFIP_EVT_SEND_MSG = 0x0140,
        PWRFIP_EVT_SEND_APU = 0x0130,
        PWRFIP_EVT_SEND_APN = 0x0131,
        PWRFIP_EVT_BA_ACTIVITY = 0x0400,
        PWRFIP_EVT_BA_STOP_TMO = 0x0401,
        PWRFIP_EVT_BA_STOP_ERR = 0x0402,
        PWRFIP_EVT_BA_STOP_USR = 0x0404,
        PWRFIP_EVT_BA_IDLE = 0x0408,
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_EVT_SEND_VAR_P | 0x8100 | A variable set-up with permanent event has been sent on the FIP network.
| The variable ID attached to this event code is saved in `.param` field of `struct pwrfip_event`
PWRFIP_EVT_SEND_VAR_T | 0x0100 | A variable set-up with temporary event (once) has been sent on the FIP network.
| The variable ID attached to this event code is saved in `.param` field of `struct pwrfip_event`
PWRFIP_EVT_RECV_VAR_P | 0x8200 | A variable set-up with permanent event has been received from the FIP network.
| The variable ID attached to this event code is saved in `.param` field of `struct pwrfip_event`
PWRFIP_EVT_RECV_VAR_T | 0x0200 | A variable set-up with temporary event (once) has been received from the FIP network.
| The variable ID attached to this event code is saved in `.param` field of `struct pwrfip_event`
PWRFIP_EVT_RECV_MSG | 0x0240 | A FIP message has been received from the FIP network.
PWRFIP_EVT_SEND_MSG | 0x0140 | A FIP message has been sent to the FIP network.
PWRFIP_EVT_SEND_APU | 0x0130 | An urgent aperiodic variable list has been sent to the FIP network.
PWRFIP_EVT_SEND_APN | 0x0131 | An normal aperiodic variable list has been sent to the FIP network.
PWRFIP_EVT_BA_ACTIVITY | 0x0400 | The bus arbiter is running. The local node is master.
PWRFIP_EVT_BA_STOP_TMO | 0x0401 | The bus arbiter has stopped on timeout.
| This event occurs when the macrocycle executes a waiting window (with external trigger waiting). If the external signal does not occur within the configured time, this event is emitted and the bus arbiter stops.
PWRFIP_EVT_BA_STOP_ERR | 0x0402 | The bus arbiter has stopped on network fault.
| This event occurs if the macrocycle executes an unknown or incorrect program instruction code. (see `struct pwrfip_ba_wind_cfg` - `.type` field) It can also occur during the start-up phase of the macrocycle, if tx errors are reported during sending of 3 padding frames.
PWRFIP_EVT_BA_STOP_USR | 0x0404 | The bus arbiter has been stopped by an user command.
PWRFIP_EVT_BA_IDLE | 0x0408 | The bus arbiter has switched to IDLE mode. Another BA is already active on the network.

### 6.8. evt_type

Description

  FIP event type.

Definition

    enum pwrfip_evt_type {
        PWRFIP_EVT_TYPE_NONE,
        PWRFIP_EVT_TYPE_PERMANENT_ID,
        PWRFIP_EVT_TYPE_PERMANENT,
        PWRFIP_EVT_TYPE_TEMPORARY,
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_EVT_TYPE_NONE | 0 | No event.
PWRFIP_EVT_TYPE_PERMANENT_ID | 1 | Permanent event on request detection. Raises a synchronous event each time the specific ID_DAT frame is detected on network.
| This event - attached to a prod/cons variable - is equivalent to a synchonization variable but with a defined payload. An IRQ is raised each time the event appears.
PWRFIP_EVT_TYPE_PERMANENT | 2 | Permanent event on response detection. Adds an entry to node event queue each time the specific RP_DAT frame is detected on network.
| This event is asynchronous. There exists two ways to dequeue it: Polling method: The user has to call periodically the `pwrfip_its_process()` function. Interrupt method: By configuring at least one synchronous event attached to the FIP periodic cycle.
PWRFIP_EVT_TYPE_TEMPORARY | 3 | Temporary event on response detection. Adds an entry to node event queue only once at the specific RP_DAT frame detection.
| This event is asynchronous. (see PWRFIP_EVT_TYPE_PERMANENT)

### 6.9. frame_type

Description

  Frame type.

Definition

    enum pwrfip_frame_type {
        _PWRFIP_FRM_TYPE_MIN = 1,
        PWRFIP_FRM_FIP = _PWRFIP_FRM_TYPE_MIN,
        PWRFIP_FRM_WORLDFIP,
        _PWRFIP_FRM_TYPE_MAX,
        _PWRFIP_FRM_TYPE_UNKNOWN = 0,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_FRM_TYPE_MIN | 1 | Minimum valid enum code for frame type.
PWRFIP_FRM_FIP | 1 | FIP frame type.
| Type of frame delimiters and CRC UTE (Union Technique de l'Electricité)
PWRFIP_FRM_WORLDFIP | 2 | WorldFIP frame type.
| Type of frame delimiters and CRC IEC (International Electrotechnical Commission)
_PWRFIP_FRM_TYPE_MAX | 3 | Maximum enum code for frame type.
_PWRFIP_FRM_TYPE_UNKNOWN | 0 | Unknown frame type.

### 6.10. medium_cmd_flag

Description

  Medium management command.
  The PowerFIP coprocessor provides a medium redundancy management solution for a FIP/WorldFIP bi-medium connection node. These commands allow to manage these two FIP channels.

Definition

    enum pwrfip_medium_cmd_flag {
        PWRFIP_MEDIUM_CMD_ENABLE_CH_1 = (1 << 0),
        PWRFIP_MEDIUM_CMD_DISABLE_CH_1 = (1 << 1),
        PWRFIP_MEDIUM_CMD_ENABLE_CH_2 = (1 << 2),
        PWRFIP_MEDIUM_CMD_DISABLE_CH_2 = (1 << 3),
        PWRFIP_MEDIUM_CMD_ENABLE_CH_1_2 = ((PWRFIP_MEDIUM_CMD_ENABLE_CH_1) |
                                           (PWRFIP_MEDIUM_CMD_ENABLE_CH_2)),
        PWRFIP_MEDIUM_CMD_DISABLE_CH_1_2 = ((PWRFIP_MEDIUM_CMD_DISABLE_CH_1) |
                                           (PWRFIP_MEDIUM_CMD_DISABLE_CH_2)),
        PWRFIP_MEDIUM_CMD_CLEAR_TX_ERR = (1 << 4),
        PWRFIP_MEDIUM_CMD_RESET_CH_1 = (1 << 5),
        PWRFIP_MEDIUM_CMD_RESET_CH_2 = (1 << 6),
        PWRFIP_MEDIUM_CMD_RESET_CH_1_2 = ((PWRFIP_MEDIUM_CMD_RESET_CH_1) |
                                          (PWRFIP_MEDIUM_CMD_RESET_CH_2)),
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_MEDIUM_CMD_ENABLE_CH_1 | 0x0001 | Enable FIP channel 1.
PWRFIP_MEDIUM_CMD_DISABLE_CH_1 | 0x0002 | Disable FIP channel 1.
PWRFIP_MEDIUM_CMD_ENABLE_CH_2 | 0x0004 | Enable FIP channel 2.
PWRFIP_MEDIUM_CMD_DISABLE_CH_2 | 0x0008 | Disable FIP channel 2.
PWRFIP_MEDIUM_CMD_ENABLE_CH_1_2 | 0x0005 | Enable both FIP channels.
PWRFIP_MEDIUM_CMD_DISABLE_CH_1_2 | 0x000a | Diable both FIP channels.
PWRFIP_MEDIUM_CMD_CLEAR_TX_ERR | 0x0010 | Clear TX error flag for both channels.
PWRFIP_MEDIUM_CMD_RESET_CH_1 | 0x0020 | Reset FIP channel 1.
PWRFIP_MEDIUM_CMD_RESET_CH_2 | 0x0040 | Reset FIP channel 2.
PWRFIP_MEDIUM_CMD_RESET_CH_1_2 | 0x0060 | Reset both channels.

### 6.11. medium_state

Description

  Flags describing FIP medium (channels) state.

Definition

    enum pwrfip_medium_state {
        PWRFIP_MEDIUM_STATE_CH1_VALID = (1 << 0),
        PWRFIP_MEDIUM_STATE_CH2_VALID = (1 << 1),
        PWRFIP_MEDIUM_STATE_CH1_TX_ERROR = (1 << 2),
        PWRFIP_MEDIUM_STATE_CH2_TX_ERROR = (1 << 3),
        PWRFIP_MEDIUM_STATE_CH1_WATCHDOG = (1 << 4),
        PWRFIP_MEDIUM_STATE_CH2_WATCHDOG = (1 << 5),
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_MEDIUM_STATE_CH1_VALID | 0x0001 | Channel 1 is active
PWRFIP_MEDIUM_STATE_CH2_VALID | 0x0002 | Channel 2 is active
PWRFIP_MEDIUM_STATE_CH1_TX_ERROR | 0x0004 | TX Error detected on channel 1
PWRFIP_MEDIUM_STATE_CH2_TX_ERROR | 0x0008 | TX Error detected on channel 2
PWRFIP_MEDIUM_STATE_CH1_WATCHDOG | 0x0010 | Watchdog on channel 1. MAU has to be reset.
PWRFIP_MEDIUM_STATE_CH2_WATCHDOG | 0x0020 | Watchdog on channel 2. MAU has to be reset.

### 6.12. msg_err_code

Description

  FIP message error codes after read/write operation.

Definition

    enum pwrfip_msg_err_code {
        _PWRFIP_MSG_OK,
        _PWRFIP_MSG_ERR_MIN,
        /* configuration errors */
        PWRFIP_MSG_TX_CH_UNKNOWN = _PWRFIP_MSG_ERR_MIN,
        /* context error */
        PWRFIP_MSG_TYPE_BAD,
        PWRFIP_MSG_LEN_BAD,
        /* -> rx msg */
        PWRFIP_MSG_RX_FIFO_EMPTY,
        /* -> tx msg */
        PWRFIP_MSG_TX_FIFO_EMPTY,
        PWRFIP_MSG_TX_FIFO_FULL,
        PWRFIP_MSG_TX_TMO,
        PWRFIP_MSG_TX_ACK_TMO,
        PWRFIP_MSG_TX_ACK_NACK,
        _PWRFIP_MSG_ERR_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_MSG_OK | 0 | No error. Operation correctly performed.
_PWRFIP_MSG_ERR_MIN | 1 | Minimal error code.
PWRFIP_MSG_TX_CH_UNKNOWN | 1 | Unknown message TX channel number.
PWRFIP_MSG_TYPE_BAD | 2 | Bad message type. See `.type` field of `struct pwrfip_msg_cfg`.
PWRFIP_MSG_LEN_BAD | 3 | Bad message length. A message byte size (header + payload) should be in [7;262] range.
PWRFIP_MSG_RX_FIFO_EMPTY | 4 | RX message queue is empty.
PWRFIP_MSG_TX_FIFO_EMPTY | 5 | TX message queue is empty.
PWRFIP_MSG_TX_FIFO_FULL | 6 | TX message queue is full.
PWRFIP_MSG_TX_TMO | 7 | Message not sent and timeout expired (both mode: ack/noack). It’s a local timeout. No transmission attempt on the network by the local node. Maybe TX message channel is not correctly set-up, or the BA node never queries the identifier attached to the TX channel.
PWRFIP_MSG_TX_ACK_TMO | 8 | Message sent but never acked (ack mode only). It’s a remote timeout. No ACK frame received despite SDA request. The remote target node is absent or not working properly.
PWRFIP_MSG_TX_ACK_NACK | 9 | Message sent but negatively acknowledged (ack mode only). The remote target node has sent a NACK frame (RP_ACKme/RP_ACKmo) to reject the received message. Maybe the message reception queue of the remote target node is full or not correctly set-up.
_PWRFIP_MSG_ERR_MAX | 10 | Maximum error code

### 6.13. msg_rx_seg_cap

Description

  Message reception capability for the node depending on the destination segment of the FIP message.

| A FIP node can be configured to be more or less sensitive to receiving FIP messages from the network. Depending on the header of the received message (destination address), it is possible to filter all messages destined to a particular FIP segment or to accept only particular header values.

Definition

    enum pwrfip_msg_rx_seg_cap {
        _PWRFIP_MSG_SEG_CAP_MIN = 0,
        PWRFIP_MSG_SEG_IGNORE = _PWRFIP_MSG_SEG_CAP_MIN,
        PWRFIP_MSG_SEG_ACCEPT_ALL,
        PWRFIP_MSG_SEG_ACCEPT_LTD,
        _PWRFIP_MSG_SEG_CAP_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_MSG_SEG_CAP_MIN | 0 | Minimum capacity value.
PWRFIP_MSG_SEG_IGNORE | 0 | Ignore all messages sent to the segment.
PWRFIP_MSG_SEG_ACCEPT_ALL | 1 | Accept all messages sent to the segment (regardless of the DSAP).
PWRFIP_MSG_SEG_ACCEPT_LTD | 2 | Limited acceptance.
| Only if the DSAP is configured for the node. See `.rx.dst.lsap` field of `struct pwrfip_msg_cfg`.
_PWRFIP_MSG_SEG_CAP_MAX | 3 | Maximum capacity value.

### 6.14. msg_tx_ack_mode

Description

  Acknowledgement mode for a FIP message.

Definition

    enum pwrfip_msg_tx_ack_mode {
        _PWRFIP_MSG_TX_ACK_MODE_MIN = 0,
        PWRFIP_MSG_TX_ACK_MODE_SDN = _PWRFIP_MSG_TX_ACK_MODE_MIN,
        PWRFIP_MSG_TX_ACK_MODE_SDA,
        _PWRFIP_MSG_TX_ACK_MODE_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_MSG_TX_ACK_MODE_MIN | 0 | Mininum TX acknowledgment mode value
PWRFIP_MSG_TX_ACK_MODE_SDN | 0 | Send message without acknowledgment request (SDN)
PWRFIP_MSG_TX_ACK_MODE_SDA | 1 | Send message with acknowledgment request (SDA)
_PWRFIP_MSG_TX_ACK_MODE_MAX | 2 | Maximum TX acknowledgment mode value

### 6.15. msg_tx_channel

Description

  Transmission channels number for FIP messages.

Definition

    enum pwrfip_msg_tx_channel {
        _PWRFIP_MSG_TX_CH_MIN = 0,
        PWRFIP_MSG_TX_CH_APER = _PWRFIP_MSG_TX_CH_MIN,
        PWRFIP_MSG_TX_CH_PER_1,
        PWRFIP_MSG_TX_CH_PER_2,
        PWRFIP_MSG_TX_CH_PER_3,
        PWRFIP_MSG_TX_CH_PER_4,
        PWRFIP_MSG_TX_CH_PER_5,
        PWRFIP_MSG_TX_CH_PER_6,
        PWRFIP_MSG_TX_CH_PER_7,
        PWRFIP_MSG_TX_CH_PER_8,
        _PWRFIP_MSG_TX_CH_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_MSG_TX_CH_MIN | 0 | Mininum message TX channel value
PWRFIP_MSG_TX_CH_APER | 0 | Aperiodic message transmission channel
PWRFIP_MSG_TX_CH_PER_1 | 1 | Periodic message transmission channel 1
PWRFIP_MSG_TX_CH_PER_2 | 2 | Periodic message transmission channel 2
PWRFIP_MSG_TX_CH_PER_3 | 3 | Periodic message transmission channel 3
PWRFIP_MSG_TX_CH_PER_4 | 4 | Periodic message transmission channel 4
PWRFIP_MSG_TX_CH_PER_5 | 5 | Periodic message transmission channel 5
PWRFIP_MSG_TX_CH_PER_6 | 6 | Periodic message transmission channel 6
PWRFIP_MSG_TX_CH_PER_7 | 7 | Periodic message transmission channel 7
PWRFIP_MSG_TX_CH_PER_8 | 8 | Periodic message transmission channel 8
_PWRFIP_MSG_TX_CH_MAX | 9 | Maximum message TX channel value

### 6.16. msg_type

Description

  FIP message type.

Definition

    enum pwrfip_msg_type {
        _PWRFIP_MSG_TYPE_MIN = 0,
        PWRFIP_MSG_TYPE_RECV = _PWRFIP_MSG_TYPE_MIN,
        PWRFIP_MSG_TYPE_SEND,
        _PWRFIP_MSG_TYPE_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_MSG_TYPE_MIN | 0 | Minimum message type value
PWRFIP_MSG_TYPE_RECV | 0 | Message to receive
PWRFIP_MSG_TYPE_SEND | 1 | Message to send
_PWRFIP_MSG_TYPE_MAX | 2 | Maximum message type value

### 6.17. node_operation

Description

  Operation type inside a FIP node.

Definition

    enum pwrfip_node_operation {
        _PWRFIP_NODE_OP_UNKNOWN,
        PWRFIP_NODE_OP_WAIT_RX_RP_FRM,
        PWRFIP_NODE_OP_WAIT_TX_RP_FRM,
        PWRFIP_NODE_OP_WAIT_RX_ID_FRM,
        PWRFIP_NODE_OP_WAIT_TX_ID_FRM,
        _PWRFIP_NODE_OP_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_NODE_OP_UNKNOWN | 0 | Unknown operation
PWRFIP_NODE_OP_WAIT_RX_RP_FRM | 1 | Wait for reception of RP_XX frame
PWRFIP_NODE_OP_WAIT_TX_RP_FRM | 2 | RP_XX frame transmission in progress
PWRFIP_NODE_OP_WAIT_RX_ID_FRM | 3 | Wait for reception of ID_XX frame
PWRFIP_NODE_OP_WAIT_TX_ID_FRM | 4 | ID_XX frame transmission in progress
_PWRFIP_NODE_OP_MAX | 5 | Max node operation

### 6.18. node_state

Description

  FSM (Finite State Machine) for a FIP node.

Definition

    enum pwrfip_node_state {
        PWRFIP_NODE_STATE_INITIAL,
        PWRFIP_NODE_STATE_LOADED,
        PWRFIP_NODE_STATE_READY,
        PWRFIP_NODE_STATE_RUNNING,
        _PWRFIP_NODE_STATE_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_NODE_STATE_INITIAL | 0 | Initial state. No config loaded
PWRFIP_NODE_STATE_LOADED | 1 | General node config loaded.
PWRFIP_NODE_STATE_READY | 2 | User context loaded (AE/LE). Here, FIP node is in stopped state, and is ready to start.
PWRFIP_NODE_STATE_RUNNING | 3 | Running state. Node is active on network
_PWRFIP_NODE_STATE_MAX | 4 | Max node state number

### 6.19. sm_var_type

Description

  FIP system management variable type (SM-MPS).

Definition

    enum pwrfip_sm_var_type {
        PWRFIP_SM_VAR_IDENT,
        PWRFIP_SM_VAR_REPORT,
        PWRFIP_SM_VAR_PRESENCE,
        PWRFIP_SM_VAR_SEG_PAR,
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_SM_VAR_IDENT | 0 | Identification SM-MPS variable (0x10XY).
PWRFIP_SM_VAR_REPORT | 1 | Report SM-MPS variable (0x11XY).
PWRFIP_SM_VAR_PRESENCE | 2 | Presence SM-MPS variable (0x14XY).
PWRFIP_SM_VAR_SEG_PAR | 3 | Segment parameter variable (0x9008).

### 6.20. var_aper_channel_type

Description

  Priority level for the channel dedicated to aperiodic variable requests.

Definition

    enum pwrfip_var_aper_channel_type {
        PWRFIP_VAR_APER_CH_NORMAL = 0,
        PWRFIP_VAR_APER_CH_URGENT,
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_VAR_APER_CH_NORMAL | 0 | Normal priority.
PWRFIP_VAR_APER_CH_URGENT | 1 | Urgent priority.

### 6.21. var_err_code

Description

  FIP variable error codes after read/write operation.

Definition

    enum pwrfip_var_err_code {
        _PWRFIP_VAR_OK,
        _PWRFIP_VAR_ERR_MIN,
        /* configuration errors */
        PWRFIP_VAR_ID_UNKNOWN = _PWRFIP_VAR_ERR_MIN,
        PWRFIP_VAR_NOT_PRODUCING,
        PWRFIP_VAR_NOT_CONSUMING,
        PWRFIP_VAR_TX_APER_CH_UNKNOWN,
        /* context error */
        PWRFIP_VAR_PDU_INCONSISTENT,
        PWRFIP_VAR_LEN_TOO_LONG,
        PWRFIP_VAR_LEN_TOO_SHORT,
        PWRFIP_VAR_NEVER_RECEIVED,
        PWRFIP_VAR_TX_APER_FIFO_EMPTY,
        PWRFIP_VAR_TX_APER_FIFO_FULL,
        /* payload error */
        /* -> cons var */
        PWRFIP_VAR_NOT_MEANING,
        PWRFIP_VAR_NOT_REFRESH,
        PWRFIP_VAR_NOT_PROMPT,
        PWRFIP_VAR_BAD_PROMPT_PER,
        /* -> prod var */
        PWRFIP_VAR_BAD_REFRESH_PER,
        _PWRFIP_VAR_ERR_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
_PWRFIP_VAR_OK | 0 | No error. Operation correctly performed.
_PWRFIP_VAR_ERR_MIN | 1 | Minimal error code.
PWRFIP_VAR_ID_UNKNOWN | 1 | Unknown variable ID. The FIP identifier is not set to support a variable. No RP_DAT frame attached to local database.
PWRFIP_VAR_NOT_PRODUCING | 2 | The FIP variable is not set to production.
PWRFIP_VAR_NOT_CONSUMING | 3 | The FIP variable is not set to consumption.
PWRFIP_VAR_TX_APER_CH_UNKNOWN | 4 | Unknown TX channel number for aperiodic variable.
| Normal channel number = 0 Urgent channel number = 1
PWRFIP_VAR_PDU_INCONSISTENT | 5 | Inconsistent variable PDU (Protocol Data Unit). The PDU read on the FIP network does not match with the PDU configured for the variable.
PWRFIP_VAR_LEN_TOO_LONG | 6 | The size of the variable read on the FIP network is longer than the one configured in the local database.
PWRFIP_VAR_LEN_TOO_SHORT | 7 | The size of the variable read on the FIP network is shorter than the one configured in the local database.
PWRFIP_VAR_NEVER_RECEIVED | 8 | The variable has never been received on the FIP node.
PWRFIP_VAR_TX_APER_FIFO_EMPTY | 9 | TX aperiodic variable queue is empty.
PWRFIP_VAR_TX_APER_FIFO_FULL | 10 | TX aperiodic variable queue is full.
PWRFIP_VAR_NOT_MEANING | 11 | The FIP variable read is not significant.
PWRFIP_VAR_NOT_REFRESH | 12 | The FIP variable is not fresh. (see production status byte)
PWRFIP_VAR_NOT_PROMPT | 13 | The FIP variable is not prompt.
PWRFIP_VAR_BAD_PROMPT_PER | 14 | Bad reading frequency for application layer (promptness). User app is not reading the FIP variable with a correct period. This may be due to excessive OS latencies.
PWRFIP_VAR_BAD_REFRESH_PER | 15 | Bad writing frequency for application layer (refreshment) User app is not writing the FIP variable with a correct period. This may be due to excessive OS latencies.
_PWRFIP_VAR_ERR_MAX | 16 | Maximum error code

### 6.22. var_flags

Description

  Set-up flags for a FIP variable

Definition

    enum pwrfip_var_flags {
        /**
         * PROD/CONS
         */
        PWRFIP_VAR_FLAGS_REFRESH = (1 << 0),
        PWRFIP_VAR_FLAGS_DYN_REFRESH = (1 << 1),
        /**
         * PROD only
         */
        PWRFIP_VAR_FLAGS_APER_VAR_REQ = (1 << 8),
        PWRFIP_VAR_FLAGS_APER_MSG_REQ = (1 << 9),
        /**
         * CONS only
         */
        PWRFIP_VAR_FLAGS_PROMPT = (1 << 12),
        PWRFIP_VAR_FLAGS_CHK_PDU_LEN = (1 << 13),

        PWRFIP_VAR_FLAGS_MAX_VAL = (1 << 15),
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_VAR_FLAGS_REFRESH | 0x0001 | Enable/Disable production status (refreshment)
| Production variable case: If this option is enabled, an extra byte - called production status - is automatically added to the end of the payload by the coprocessor. This byte is updated by the producer to inform other nodes if the payload is correcly refreshed inside its local database. Consumption variable case: If this option is enabled, the last useful byte of the frame is considered to be a production state. It is then interpreted by the coprocessor to know the freshness state of the variable consumed on the network.
PWRFIP_VAR_FLAGS_DYN_REFRESH | 0x0002 | Enable/Disable dynamic production status (eq. var_time)
| In addition to the production status byte added at the end of the user payload, 4 extra bytes are inserted by the producer to inform the production time of the variable to other nodes. This time - in microseconds - expresses the delay between the user’s write command and the actual production by the MAU of producer on the network.
PWRFIP_VAR_FLAGS_APER_VAR_REQ | 0x0100 | Enable/Disable aperiodic variable request capability
| This flag is reserved only for a variable set in production.
PWRFIP_VAR_FLAGS_APER_MSG_REQ | 0x0200 | Enable/Disable aperiodic message request capability
| This flag is reserved only for a variable set in production.
PWRFIP_VAR_FLAGS_PROMPT | 0x1000 | Enable/Disable promptness status
| This flag is reserved only for a variable set in consumption.
PWRFIP_VAR_FLAGS_CHK_PDU_LEN | 0x2000 | Enable/Disable PDU+LEN bytes frame check
| This flag is reserved only for a variable set in consumption.
PWRFIP_VAR_FLAGS_MAX_VAL | 0x8000 | Maximal setting flag for variable

### 6.23. var_type

Description

  FIP variable type.

Definition

    enum pwrfip_var_type {
        PWRFIP_VAR_TYPE_CONS,
        PWRFIP_VAR_TYPE_PROD,
        PWRFIP_VAR_TYPE_SYNC,
        _PWRFIP_VAR_TYPE_MAX,
    };

Values

Constant | Value | Description
--- | --- | ---
PWRFIP_VAR_TYPE_CONS | 0 | Consumption variable.
PWRFIP_VAR_TYPE_PROD | 1 | Production variable.
PWRFIP_VAR_TYPE_SYNC | 2 | Synchronization variable.
| No payload is attached to this kind of variable but the node is sensitive to (RX/TX) ID_DAT frame. An IRQ is raised each time the event appears and immediately signals the user-space with a synchronous event. This event attached to an ID_DAT without payload is called a pure event.
_PWRFIP_VAR_TYPE_MAX | 3 | Maximum variable type value.

## Appendix A: SM-MPS variables

The network management variables SM-MPS are automatically created and internally managed by the PowerFIP library.
These variables are useful to know the general state of the network as well as to get information about a particular FIP node.

### A.1. Identification - 0x10XY

Description

  The variable attached to the ID number 0x10XY (where XY is the node address) is called the Identification variable.
  Each node produces this variable, and its payload allows to clearly identify the node on the network.

Frame Format

Bytes | Description
--- | ---
0x50 | PDU type (SM-MPS)
0xZZ | PDU length (must not exceed 126 bytes)
0x80 | Manufacturer name field
0xZZ | Manufacturer name field length
0xZZ | First character for manufacturer name
…​ | …​
0xZZ | Last character for manufacturer name
0x81 | Model name field
0xZZ | Model name field length
0xZZ | First character for model name
…​ | …​
0xZZ | Last character for model name
0x82 | Revision field
0x01 | Revision field length
0xZZ | Revision number (ex: 0x10 for v1.0)
0x83 | Device tag name field [Optional]
0xZZ | Device tag name field length
0xZZ | First character for tag name
…​ | …​
0xZZ | Last character for tag name
0x84 | SM-MPS secondary function field
0x01 | SM-MPS secondary function field length
0x10 (fixed) | SM-MPS secondary function field value: bit0: set to 1 if loading supported bit1: set to 1 if remote reading supported bit2: set to 1 if remote control supported bit3: set to 1 if remote checking supported bit4: set to 1 if report supported the other bits are always set to 0
0x8A | Vendor field [Optional]
0xZZ | Vendor field length
0xZZ | First byte for vendor field
…​ | …​
0xZZ | Last byte for vendor field

### A.2. Report - 0x11XY

Description

  The variable attached to the ID number 0x11XY (where XY is the node address) is called the Report variable.
  Each node produces this variable, and its payload contains various node-specific status counters (rx faults, number of transactions, …​).

Frame Format

Bytes | Description
--- | ---
0x50 | PDU type (SM-MPS)
0x0F | PDU length
0x50 | Tag for counter of frames correctly received on channel 1 by Time Unit(1)
0xZZ | Counter Most Significant Byte
0xZZ | Counter Least Significant Byte
0x51 | Tag for counter of frames correctly received on channel channel 2 by Time Unit(1)
0xZZ | Counter Most Significant Byte
0xZZ | Counter Least Significant Byte
0x52 | Tag for counter of frames incorrectly received on channel 1 by Time Unit(1)
0xZZ | Counter Most Significant Byte
0xZZ | Counter Least Significant Byte
0x53 | Tag for counter of frames incorrectly received on channel 2 by Time Unit(1)
0xZZ | Counter Most Significant Byte
0xZZ | Counter Least Significant Byte
0x54 | Tag for channel status
0xZZ | Channel status (MSB) bit1: Synthesis for channel 2 (1: OK, 0: NOK)
| Result of the binary operation for channel status LSB: b1 & b3 & b5 & b7
bit0: Synthesis for channel 1 (1: OK, 0: NOK)
| Result of the binary operation for channel status LSB: b0 & b2 & b4 & b6
0xZZ | Channel status (LSB) bit7: Traffic(2) on channel 2 (1: OK, 0: NOK) bit6: Traffic(2) on channel 1 (1: OK, 0: NOK) bit5: Validity(3) on channel 2 (1: OK, 0: NOK) bit4: Validity(3) on channel 1 (1: OK, 0: NOK) bit3: RX quality(4) on channel 2 (1: OK, 0: NOK) bit2: RX quality(4) on channel 1 (1: OK, 0: NOK) bit1: TX quality(4) on channel 2 (1: OK, 0: NOK) bit0: TX quality(4) on channel 1 (1: OK, 0: NOK)

Remarks

  - (1) Time Unit corresponds to the diagnostic period of the medium. This task is internally performed by the library, and the period is automatically set according to the FIP bitrate:

    - @31.25Kbps: 1.6s

    - @1Mbps: 500ms

    - @2.5Mbps: 200ms

    - @5Mbps: 100ms

    - @12.5Mbps: 40ms

    - @25Mbps: 20ms

  - (2): Traffic signal is the measure of frames correctly received and/or transmitted on/by the channel by Time Unit(1). To be OK, you need:

    - (TX frames OK + RX frames OK) > 0

  - (3): Validity of a channel is given by the medium redundancy component.
    See `enum pwrfip_medium_state`:

    - PWRFIP_MEDIUM_STATE_CH1_VALID

    - PWRFIP_MEDIUM_STATE_CH2_VALID

  - (4): RX/TX quality is the measure of the error rate on the channel by Time Unit(1). This error threshold is set to 5% by the library.
    To be OK, you need:

    - (RX frames faults / RX frames OK) < Threshold

    - (TX frames faults / TX frames OK) < Threshold

### A.3. Presence - 0x14XY

Description

  The variable attached to the ID number 0x14XY (where XY is the node address) is called the Presence variable.
  Each node produces this variable and thus informs the other nodes of the FIP network of its presence.

Frame Format

Bytes | Description
--- | ---
0x50 | PDU type (SM-MPS)
0x05 | PDU length
0x80 | Presence parameter
0x03 | Presence parameter length
0xZZ | Identification characteristics. See: PDU length for 0x10XY 0: Unknown length 1 to 0xFE: Known length 0xFF: No identification variable
0x00 | Reserved
0xZZ | Bus Arbiter global status (about the producer). bit4-bit7: BA status: 0: BA not supported 1: BA not eligible (stopped mode) 2: BA idle (on standby) 3: BA active (master node) bit0-bit3: BA priority (if BA is supported). Range is [0;15], with 0 the highest priority.

### A.4. Presence Check - 0x9002

Description

  The variable attached to the ID number 0x9002 is called the Presence Check or Present List variable.
  This variable is produced by the master node (Bus arbiter active).
  It summarizes in a single variable the whole list of nodes presence on the network.

Frame Format

Bytes | Description
--- | ---
0x50 | PDU type (SM-MPS)
0x44 | PDU length
0x80 | Channel 1 presence list
0x20 | Channel 1 presence list length
0xZZ | Status of nodes address 0 to 7. (0: absent, 1: present) bit0: node 0 …​ bit7: node 7
…​ | …​
0xZZ | Status of nodes address 248 to 255. (0: absent, 1: present) bit0: node 248 …​ bit7: node 255
0x81 | Channel 2 presence list
0x20 | Channel 2 presence list length
0xZZ | Status of nodes address 0 to 7. (0: absent, 1: present) bit0: node 0 …​ bit7: node 7
…​ | …​
0xZZ | Status of nodes address 248 to 255. (0: absent, 1: present) bit0: node 248 …​ bit7: node 255

### A.5. BA synchronization - 0x9003

Description

  The variable attached to the ID number 0x9003 is called the BA synchronisation variable.
  This variable is produced by the master node, and indicates the current status of the Bus Arbiter on the network.

Frame Format

Bytes | Description
--- | ---
0x50 | PDU type (SM-MPS)
0x04 | PDU length
0x80 | BA synchro parameter
0x02 | BA synchro parameter length
0xZZ | Macrocycle number of current BA program
0xZZ | Physical node address of the master

### A.6. Segment Parameter - 0x9008

Description

  This variable is produced by the bus arbitrator device in order to ensure consistency of the data link protocol parameters.
  It must be consumed by any device conforming to the FRDP, FSDP or the FEDP profile in order to set its own values for production turnaround time and the T0 basic delay.

Frame Format

Bytes | Description
--- | ---
0x50 | PDU type (SM-MPS)
0x06 | PDU length
0x80 | Label
0x04 | Length
0xZZ | Silence time (T0) in microseconds
0xZZ | Segment number
0xZZ | Number of repeats for message handling
0xZZ | Production turnaround time in microseconds

## Appendix B: Glossary of acronyms

AE/LE | Application Entity/Link Entity
BA | Bus Arbiter
BSS | Block Starting Symbol
DLL | Data Link Layer
DSAP | Destination Service Access Point
LLC | Logical Link Control
LSAP | Link Service Access Point
MPS | Manufacturing Periodic/aperiodic Services
SDA | Send Data with Acknowledgement
SDN | Send Data with No acknowledgement
SM-MPS | System Management Manufacturing Periodic/aperiodic Services
SSAP | Source Service Access Point

## Appendix C: Revision History

Revision | Changes | Authors | Date
--- | --- | --- | ---
1.5.0 | Add PowerFIP-CC support (direct chip coprocessor management from API) Add new functions: `pwrfip_its_process()` `pwrfip_diag_process()` Add new structures: `struct pwrfip_proc_cfg` Add `.proc` field to `struct pwrfip_node_cfg` Add `.temperature` field to `struct pwrfip_node_status` Remove function: `pwrfip_evt_process()` | MC | 2026-03-09
1.4.0 | Add support for dynamic variable configuration (type and event): `pwrfip_var_evt_set()` `pwrfip_var_type_set()` Add new SM-MPS variable type to `enum pwrfip_sm_var_type`: PWRFIP_SM_VAR_SEG_PAR Update turn-around minimum times (10us@1Mbps, 13us@2.5Mbps) Add monomedium management for 0x9002 variable | MC | 2025-05-12
1.3.0 | Add support of FIP node watchdog timeout Add `.watchdog_ustime` field to `struct pwrfip_node_cfg` | MC | 2024-04-03
1.2.0 | New binary architectures [GNU/Linux OS] aarch64 [arm64] arm [arm32] | MC | 2023-06-27
1.1.0 | Add a protocol extension setting to extend the length of FIP variables On optic medium: payload up to 1020B On copper medium: payload up to 501B (FielDrive component limitation) Add `.prtcl_ext` field to `struct pwrfip_node_cfg` Add new bitrates to `enum pwrfip_bitrate`: PWRFIP_BITRATE_12M5 PWRFIP_BITRATE_25M Add dynamic refreshment status support Add `.time_info` field to `struct pwrfip_var` Update min/max ranges time for silence/turn-around time | MC | 2022-06-21
1.0.2 | Add support of synchronous events on ID_DAT request frame for FIP variables (prod/cons) Add new event to `enum pwrfip_evt_type`: PWRFIP_EVT_TYPE_PERMANENT_ID | MC | 2022-03-01
1.0.1 | Add multiarch powerfip lib binaries Windows: x86_64, i686 Linux: x86_64, i386 Add support for running 32-bit programs in a 64-bit kernel Remove libwinpthread-1.dll dependency for Windows PowerFIP DLL Fix an incorrect FIP coprocessor initialization from 32-bit apps | MC | 2022-01-13
1.0.0 | Add SM-MPS variables support (next): `pwrfip_sm_var_create()` `pwrfip_sm_ba_sync_get()` `pwrfip_sm_identification_get()` `pwrfip_sm_presence_list_get()` `pwrfip_sm_presence_get()` `pwrfip_sm_report_get()` Add new structure: `struct pwrfip_sm_ba_sync` `struct pwrfip_sm_identification` `struct pwrfip_sm_presence_list` `struct pwrfip_sm_presence` `struct pwrfip_sm_report` Add `.fsn` field to `struct pwrfip_dev_infos` Add `pwrfip_error_get()` Update `struct pwrfip_msg_addr` Add new errors to `enum pwrfip_error_code`: PWRFIP_ERR_AELE_VAR_NOT_FOUND | MC | 2022-01-07
0.9.0 | Add support for periodic/aperiodic message service: `pwrfip_msg_create()` `pwrfip_msg_delete()` `pwrfip_msg_tx_channel_purge()` `pwrfip_msg_send()` Add new structure: `struct pwrfip_msg_cfg` `struct pwrfip_msg_tx_cfg` `struct pwrfip_msg_rx_cfg` `struct pwrfip_msg_addr` `struct pwrfip_msg_hdr` `struct pwrfip_msg` Add `.tx_aper_fifo_size`, `.tx_per_fifo_size[8]` and `.tx_per_fifo_id[8]` fields to `struct pwrfip_node_msg_cfg` Add `.bss_bsz` and `.bss_max_bsz` fields to `struct pwrfip_node_infos` Add `.reserved[2]` field to `struct pwrfip_event` Add new errors to `enum pwrfip_error_code`: PWRFIP_ERR_CFG_VAR_TYPE_UNKNOWN PWRFIP_ERR_CFG_MSG_EXIST PWRFIP_ERR_CFG_VAR_BAD_LEN PWRFIP_ERR_CFG_MSG_TYPE_UNKNOWN PWRFIP_ERR_CFG_MSG_TX_ACK_MODE_UNKNOWN PWRFIP_ERR_CFG_MSG_TX_CH_PER_EXIST PWRFIP_ERR_CFG_MSG_TX_CH_PER_UNKNOWN PWRFIP_ERR_CFG_MSG_TX_CH_PER_NOID PWRFIP_ERR_NODE_BSS_OVERFLOW PWRFIP_ERR_NODE_MSG_CAP_NOT_SUPPORTED | MC | 2021-12-07
0.8.0 | Add support for aperiodic variable service: `pwrfip_varidlist_aper_request()` `pwrfip_varlist_aper_request()` `pwrfip_var_aper_channel_purge()` Add SM-MPS variables support: (note: internally managed by the library) Identification (0x10XY) Report (0x11XY) Presence (0x14XY) Presence Check (0x9002) BA Synchronization (0x9003) Add new structure: `struct pwrfip_node_ident_cfg` Add `.priority` field to `struct pwrfip_node_ba_cfg` Add `.ident` field to `struct pwrfip_node_cfg` Add `.pwrfip_ba_sync_handler` field to `struct pwrfip_node_cfg` Add `.user_ctx` field to `struct pwrfip_var_cfg` and `struct pwrfip_var` Add new errors to `enum pwrfip_error_code`: PWRFIP_ERR_DEV_DIAG_TASK_STARTED PWRFIP_ERR_DEV_DIAG_TASK_STOPPED PWRFIP_ERR_NODE_IDENT_PARAM PWRFIP_ERR_NODE_IDENT_LEN | MC | 2021-10-19
0.7.2 | Mailboxes processing inside the driver (Windows) High thread priority for internal library thread Add `.index` field to `struct pwrfip_dev_infos` | MC | 2021-09-21
0.7.1 | Windows 7/8/10 OS support | MC | 2021-08-04
0.7.0 | First version (Linux OS) | MC | 2021-07-05