API documentation

Here is a brief overview given for some of the most important functions, structs etc in the public API for the p-net Profinet stack.

For detailed documentation, read the include/pnet_api.h header file. It also contains error code definitions etc.

You can also build the Doxygen documentation for all functions by following the instructions given on the page “Additional Linux Details”.

Study the sample_app to get more information on how to use the API.

General

All functions return either 0 (zero) for a successful call or -1 for an unsuccessful call.

Initialization and handling

pnet_t *pnet_init(const char *netif, uint32_t tick_us, const pnet_cfg_t *p_cfg)

Initialize the Profinet stack.

This function must be called to initialize the Profinet stack.

Return

a handle to the stack instance, or NULL if an error occurred.

Parameters
  • netif: In: Name of the network interface.

  • tick_us: In: Periodic interval in us. Specify the interval between calls to pnet_handle_periodic().

  • p_cfg: In: Profinet configuration. These values are used at first startup and at factory reset.

int pnet_application_ready(pnet_t *net, uint32_t arep)

Application signals ready to exchange data.

Sends a ccontrol request to the IO-controller.

This function must be called after the application has received the pnet_state_ind() user callback with PNET_EVENT_PRMEND, in order for a connection to be established.

If this function does not see all PPM data and IOPS areas are set (by the app) then it returns error and the application must try again - otherwise the startup will hang.

Triggers the pnet_state_ind() user callback with PNET_EVENT_APPLRDY.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arep: In: The AREP

void pnet_handle_periodic(pnet_t *net)

Execute all periodic functions within the ProfiNet stack.

This function should be called periodically by the application. The period is specified by the application in the tick_us argument to pnet_init(). The period should match the expected I/O data rate to and from the device.

Parameters
  • net: InOut: The p-net stack instance

int pnet_get_ar_error_codes(pnet_t *net, uint32_t arep, uint16_t *p_err_cls, uint16_t *p_err_code)

Fetch error information from the AREP.

Return

0 If the AREP is valid. -1 if the AREP is not valid.

Parameters
  • net: InOut: The p-net stack instance

  • arep: In: The AREP.

  • p_err_cls: Out: The error class. See PNET_ERROR_CODE_1_*

  • p_err_code: Out: The error code. See PNET_ERROR_CODE_2_*

int pnet_ar_abort(pnet_t *net, uint32_t arep)

Application requests abortion of the connection.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arep: In: The AREP

int pnet_factory_reset(pnet_t *net)

Application requests factory reset of the device.

Use this for example when a local hardware switch is used to do a factory reset.

Also closes any open connections.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

void pnet_show(pnet_t *net, unsigned level)

Show information from the Profinet stack.

Parameters
  • net: InOut: The p-net stack instance

  • level: In: The amount of detail to show.

    0x0010              | Show compile time options
    0x0020              | Show CMDEV
    0x0400              | Show logbook
    0x0200              | Show diagnosis
    0x0800              | Show all sessions.
    0x1000              | Show all ARs.
    0x1001              |     include IOCR.
    0x1002              |     include data_descriptors.
    0x1003              |     include IOCR and data_descriptors.
    0x2000              | Show CFG information.
    0x4000              | Show scheduler information.
    0x8000              | Show I&M data.
    
    Bit in the level parameter:
    15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
     1                                     I&M
        1                                  Scheduler
           1                               CMINA
              1                            AR
                 1                         Sessions
                    1                      Logbook
                      1                    Diagnosis
                              1            CMDEV
                                1          Options
                                      1    More IOCR info on AR
                                        1  More IOCR info on AR
    

Plug and pull modules/submodules

int pnet_plug_module(pnet_t *net, uint32_t api, uint16_t slot, uint32_t module_ident)

Plug a module into a slot.

This function is used to plug a specific module into a specific slot.

This function may be called from the pnet_exp_module_ind() call-back function of the application.

Return

0 if a module could be plugged into the slot. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • api: In: The API identifier.

  • slot: In: The slot number.

  • module_ident: In: The module ident number.

int pnet_plug_submodule(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, uint32_t module_ident, uint32_t submodule_ident, pnet_submodule_dir_t direction, uint16_t length_input, uint16_t length_output)

Plug a sub-module into a sub-slot.

This function is used to plug a specific sub-module into a specific sub-slot.

This function may be called from the pnet_exp_submodule_ind call-back function of the application.

If a module has not been plugged into the designated slot then it will be plugged automatically by this function.

Return

0 if the sub-module could be plugged into the sub-slot. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • api: In: The API identifier.

  • slot: In: The slot number.

  • subslot: In: The sub-slot number.

  • module_ident: In: The module ident number.

  • submodule_ident: In: The sub-module ident number.

  • direction: In: The direction of data.

  • length_input: In: The size in bytes of the input data.

  • length_output: In: The size in bytes of the output data.

int pnet_pull_module(pnet_t *net, uint32_t api, uint16_t slot)

Pull a module from a slot.

This function may be used to unplug a module from a specific slot.

This function internally calls pnet_pull_submodule() on any plugged sub-modules before pulling the module itself.

Return

0 if a module could be pulled from the slot. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • api: In: The API identifier.

  • slot: In: The slot number.

int pnet_pull_submodule(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot)

Pull a sub-module from a sub-slot.

This function may be used to unplug a sub-module from a specific sub-slot.

Return

0 if the sub-module could be pulled from the sub-slot. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • api: In: The API identifier.

  • slot: In: The slot number.

  • subslot: In: The sub-slot number.

Periodic data

int pnet_input_set_data_and_iops(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, const uint8_t *p_data, uint16_t data_len, uint8_t iops)

Updates the IOPS and data of one sub-slot to send to the controller.

This function may be called to set new data and IOPS values of a sub-slot to send to the controller.

Return

0 if a sub-module data and IOPS was set. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • api: In: The API.

  • slot: In: The slot.

  • subslot: In: The sub-slot.

  • p_data: In: Data buffer.

  • data_len: In: Bytes in data buffer.

  • iops: In: The device provider status.

int pnet_input_get_iocs(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, uint8_t *p_iocs)

Fetch the controller consumer status of one sub-slot.

This function may be called to retrieve the IOCS value of a sub-slot sent from the controller.

Return

0 if a sub-module IOCS was set. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • api: In: The API.

  • slot: In: The slot.

  • subslot: In: The sub-slot.

  • p_iocs: Out: The controller consumer status.

int pnet_output_get_data_and_iops(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, bool *p_new_flag, uint8_t *p_data, uint16_t *p_data_len, uint8_t *p_iops)

Retrieve latest sub-slot data and IOPS received from the controller.

This function may be called to retrieve the latest data and IOPS values of a sub-slot sent from the controller.

If a valid new data (and IOPS) frame has arrived from the IO-controller since your last call to this function (regardless of the slot/subslot arguments) then the flag p_new_flag is set to true, else it is set to false. Note that this does not check whether the data content has changed from any previous frame.

Note that the latest data and IOPS values are copied to the application buffers regardless of the value of p_new_flag.

Return

0 if a sub-module data and IOPS is retrieved. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • api: In: The API.

  • slot: In: The slot.

  • subslot: In: The sub-slot.

  • p_new_flag: Out: true if new data.

  • p_data: Out: The received data.

  • p_data_len: In: Size of receive buffer. Out: Received number of data bytes.

  • p_iops: Out: The controller provider status (IOPS).

int pnet_output_set_iocs(pnet_t *net, uint32_t api, uint16_t slot, uint16_t subslot, uint8_t iocs)

Set the device consumer status for one sub-slot.

This function is use to set the device consumer status (IOCS) of a specific sub-slot.

Return

0 if a sub-module IOCS was set. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • api: In: The API.

  • slot: In: The slot.

  • subslot: In: The sub-slot.

  • iocs: In: The device consumer status.

int pnet_set_provider_state(pnet_t *net, bool run)

Implements the “Local set Provider State” primitive.

The application should call this function at least once during startup to set the provider status of frames sent to the controller.

The application may call this function at any time, e.g., to signal a temporary inability to produce new application data to the controller.

Its effect is similar to setting IOPS to PNET_IOXS_BAD for all sub-slots.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • run: In: true to set state to “run”.

Redundant state etc

int pnet_set_state(pnet_t *net, bool primary)

Set the state to “Primary” or “Backup” in the cyclic data sent to the IO-Controller.

Implements the “Local Set State” primitive.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • primary: In: true to set state to “primary”.

int pnet_set_redundancy_state(pnet_t *net, bool redundant)

Set the state to redundant in the cyclic data sent to the IO-Controller.

Implements the “Local Set Redundancy State” primitive.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • redundant: In: true to set state to “redundant”.

Alarms and diagnostics

void pnet_create_log_book_entry(pnet_t *net, uint32_t arep, const pnet_pnio_status_t *p_pnio_status, uint32_t entry_detail)

Application creates an entry in the log book.

This function is used to insert an entry into the Profinet log-book. Controllers may read the entire log-book using IODRead requests.

Parameters
  • net: InOut: The p-net stack instance

  • arep: In: The AREP.

  • p_pnio_status: In: The PNIO status.

  • entry_detail: In: Additional application information. Manufacturer specific.

int pnet_alarm_send_process_alarm(pnet_t *net, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t payload_usi, uint16_t payload_len, const uint8_t *p_payload)

Application issues a process alarm.

This function may be used by the application to issue a process alarm. Such alarms are sent to the controller using high-priority alarm messages.

Optional payload may be attached to the alarm. If payload_usi is != 0 then the payload_usi and the payload at p_payload is attached to the alarm.

After calling this function the application must wait for the pnet_alarm_cnf() callback before sending another alarm. This function fails if the application does not wait for the pnet_alarm_cnf() between sending two alarms.

This functionality is used for alarms triggered by the IO-device.

Return

0 if the operation succeeded. -1 if an error occurred (or waiting for ACK from controller: re-try later).

Parameters
  • net: InOut: The p-net stack instance

  • arep: In: The AREP.

  • api: In: The API.

  • slot: In: The slot.

  • subslot: In: The sub-slot.

  • payload_usi: In: The USI for the payload. Max 0x7fff

  • payload_len: In: Length in bytes of the payload. Max 1408.

  • p_payload: In: The alarm payload (USI specific format).

int pnet_alarm_send_ack(pnet_t *net, uint32_t arep, const pnet_alarm_argument_t *p_alarm_argument, const pnet_pnio_status_t *p_pnio_status)

Application acknowledges the reception of an alarm from the controller.

This function sends an ACK to the controller. This function must be called by the application after receiving an alarm in the pnet_alarm_ind() call-back. Failure to do so within the timeout specified in the connect of the controller will make the controller re-send the alarm.

This functionality is used for alarms triggered by the IO-controller.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arep: In: The AREP.

  • p_alarm_argument: In: The alarm argument (with slot, subslot, alarm_type etc)

  • p_pnio_status: In: Detailed ACK status.

int pnet_diag_std_add(pnet_t *net, uint32_t arep, const pnet_diag_source_t *p_diag_source, pnet_diag_ch_prop_type_values_t ch_bits, pnet_diag_ch_prop_maint_values_t severity, uint16_t ch_error_type, uint16_t ext_ch_error_type, uint32_t ext_ch_add_value, uint32_t qual_ch_qualifier)

Add a diagnosis entry, in the standard format.

The channel error types and the extended channel error types are defined in Profinet 2.4 Services Annex F.

This sends a diagnosis alarm.

Uses the “Qualified channel diagnosis” format on the wire.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance.

  • arep: In: The AREP.

  • p_diag_source: In: Slot, subslot, channel, direction etc.

  • ch_bits: In: Number of bits in the channel.

  • severity: In: Diagnosis severity.

  • ch_error_type: In: The channel error type.

  • ext_ch_error_type: In: The extended channel error type (more details on the channel error type). Use 0 if not given.

  • ext_ch_add_value: In: The extended channel error additional value. Typically a measurement value (for example number of dropped packets) related to the error.

  • qual_ch_qualifier: In: More detailed severity information. Used when severity = PNET_DIAG_CH_PROP_MAINT_QUALIFIED. Max one bit should be set. Use 0 otherwise.

int pnet_diag_std_update(pnet_t *net, uint32_t arep, const pnet_diag_source_t *p_diag_source, uint16_t ch_error_type, uint16_t ext_ch_error_type, uint32_t ext_ch_add_value)

Update the “extended channel error additional value”, for a diagnosis entry in the standard format.

This sends a diagnosis alarm.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance.

  • arep: In: The AREP.

  • p_diag_source: In: Slot, subslot, channel, direction etc.

  • ch_error_type: In: The channel error type.

  • ext_ch_error_type: In: The extended channel error type (more details on the channel error type). Use 0 if not given.

  • ext_ch_add_value: In: New extended channel error additional value. Typically a measurement value (for example number of dropped packets) related to the error.

int pnet_diag_std_remove(pnet_t *net, uint32_t arep, const pnet_diag_source_t *p_diag_source, uint16_t ch_error_type, uint16_t ext_ch_error_type)

Remove a diagnosis entry in the standard format.

An error is returned if the diagnosis doesn’t exist.

This sends a diagnosis alarm.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance.

  • arep: In: The AREP.

  • p_diag_source: In: Slot, subslot, channel, direction etc.

  • ch_error_type: In: The channel error type.

  • ext_ch_error_type: In: The extended channel error type (more details on the channel error type). Use 0 if not given.

int pnet_diag_usi_add(pnet_t *net, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t usi, const uint8_t *p_manuf_data)

Add a diagnosis entry in manufacturer-specified (“USI”) format.

If the diagnosis already exists, it is updated. Use pnet_diag_usi_update() instead if you would like to have an error if the diagnosis is missing when trying to update it.

A diagnosis in USI format is always assigned to the channel “whole

submodule” (not individual channels). The severity is always “Fault”.

It is recommended to use the standard diagnosis format in most cases. Use the manufacturer specific format (“USI format”) only if it’s not possible to use the standard format.

This sends a diagnosis alarm.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance.

  • arep: In: The AREP.

  • api: In: The API.

  • slot: In: The slot.

  • subslot: In: The sub-slot.

  • usi: In: The USI. Range 0..0x7fff

  • p_manuf_data: In: The manufacturer specific diagnosis data. Size PF_DIAG_MANUF_DATA_LEN.

int pnet_diag_usi_update(pnet_t *net, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t usi, const uint8_t *p_manuf_data)

Update the manufacturer specific data, for a diagnosis entry in manufacturer-specified (“USI”) format.

An error is returned if the diagnosis doesn’t exist. Use pnet_diag_usi_add() instead if you would like to create the missing diagnosis when trying to update it.

This sends a diagnosis alarm.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance.

  • arep: In: The AREP.

  • api: In: The API.

  • slot: In: The slot.

  • subslot: In: The sub-slot.

  • usi: In: The USI. Range 0..0x7fff

  • p_manuf_data: In: New manufacturer specific diagnosis data. Size PF_DIAG_MANUF_DATA_LEN.

int pnet_diag_usi_remove(pnet_t *net, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t usi)

Remove a diagnosis entry in manufacturer-specified (“USI”) format.

An error is returned if the diagnosis doesn’t exist.

This sends a diagnosis alarm.

Return

0 if the operation succeeded. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance.

  • arep: In: The AREP.

  • api: In: The API.

  • slot: In: The slot.

  • subslot: In: The sub-slot.

  • usi: In: The USI. Range 0..0x7fff

Callbacks

The application should define call-back functions which are called by the stack when specific events occurs within the stack.

Note that most of these functions are mandatory in the sense that they must exist and return 0 for a functioning stack. Some functions are required to perform specific functionality.

typedef int (*pnet_connect_ind)(pnet_t *net, void *arg, uint32_t arep, pnet_result_t *p_result)

Indication to the application that a Connect request was received from the controller.

This application call-back function is called by the Profinet stack on every Connect request from the Profinet controller.

The connection will be opened if this function returns 0 (zero) and the stack is otherwise able to establish a connection.

If this function returns something other than 0 (zero) then the Connect request is refused by the device. In case of error the application should provide error information in p_result.

It is optional to implement this callback (assumes success if not implemented).

Return

0 on success. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • p_result: Out: Detailed error information.

typedef int (*pnet_release_ind)(pnet_t *net, void *arg, uint32_t arep, pnet_result_t *p_result)

Indication to the application that a Release request was received from the controller.

This application call-back function is called by the Profinet stack on every Release request from the Profinet controller.

The connection will be closed regardless of the return value from this function. In case of error the application should provide error information in p_result.

It is optional to implement this callback (assumes success if not implemented).

Return

0 on success. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • p_result: Out: Detailed error information.

typedef int (*pnet_dcontrol_ind)(pnet_t *net, void *arg, uint32_t arep, pnet_control_command_t control_command, pnet_result_t *p_result)

Indication to the application that a DControl request was received from the controller.

This application call-back function is called by the Profinet stack on every DControl request from the Profinet controller.

The application is not required to take any action but the function must return 0 (zero) for proper function of the stack. If this function returns something other than 0 (zero) then the DControl request is refused by the device. In case of error the application should provide error information in p_result.

It is optional to implement this callback (assumes success if not implemented).

Return

0 on success. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • control_command: In: The DControl command code.

  • p_result: Out: Detailed error information.

typedef int (*pnet_ccontrol_cnf)(pnet_t *net, void *arg, uint32_t arep, pnet_result_t *p_result)

Indication to the application that a CControl confirmation was received from the controller.

This application call-back function is called by the Profinet stack on every CControl confirmation from the Profinet controller.

The application is not required to take any action. The return value from this call-back function is ignored by the Profinet stack. In case of error the application should provide error information in p_result.

It is optional to implement this callback (assumes success?).

Return

0 on success. Other values are ignored.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • p_result: Out: Detailed error information.

typedef int (*pnet_state_ind)(pnet_t *net, void *arg, uint32_t arep, pnet_event_values_t state)

Indication to the application that a state transition has occurred within the Profinet stack.

This application call-back function is called by the Profinet stack on specific state transitions within the Profinet stack.

At the very least the application must react to the PNET_EVENT_PRMEND state transition. After this event the application must call pnet_application_ready(), when it has finished its setup and it is ready to exchange data.

The return value from this call-back function is ignored by the Profinet stack.

It is optional to implement this callback (but then it would be difficult to know when to call the pnet_application_ready() function).

Return

0 on success. Other values are ignored.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • state: In: The state transition event. See pnet_event_values_t.

typedef int (*pnet_reset_ind)(pnet_t *net, void *arg, bool should_reset_application, uint16_t reset_mode)

Indication to the application that a reset request was received from the IO-controller.

The IO-controller can ask for communication parameters or application data to be reset, or to do a factory reset.

This application call-back function is called by the Profinet stack on every reset request (via the DCP “Set” command) from the Profinet controller.

The application should reset the application data if should_reset_application is true. For other cases this callback is triggered for diagnostic reasons.

The return value from this call-back function is ignored by the Profinet stack.

It is optional to implement this callback (if you do not have any application data that could be reset).

Reset modes:

  • 0: (Power-on reset, not from IO-controller. Will not trigger this.)

  • 1: Reset application data

  • 2: Reset communication parameters (done by the stack)

  • 99: Reset all (factory reset).

The reset modes 1-9 (out of which 1 and 2 are supported here) are defined by the Profinet standard. Value 99 is used here to indicate that the IO-controller has requested a factory reset via another mechanism.

In order to remain responsive to DCP communication and Ethernet switching, the device should not do a hard or soft reset for reset mode 1 or 2. It is allowed for the factory reset case (but not mandatory).

No arep information is available, as this callback typically is triggered when there is no active connection.

Return

0 on success. Other values are ignored.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • should_reset_application: In: True if the user should reset the application data.

  • reset_mode: In: Detailed reset information.

typedef int (*pnet_signal_led_ind)(pnet_t *net, void *arg, bool led_state)

Indication to the application that the Profinet signal LED should change state.

Use this callback to implement control of the LED.

It is optional to implement this callback (but a compliant Profinet device must have a signal LED)

No arep information is available, as this callback typically is triggered when there is no active connection.

Return

0 on success. -1 if an error occurred. Will trigger a log message.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • led_state: In: True if the signal LED should be on.

typedef int (*pnet_read_ind)(pnet_t *net, void *arg, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t idx, uint16_t sequence_number, uint8_t **pp_read_data, uint16_t *p_read_length, pnet_result_t *p_result)

Indication to the application that an IODRead request was received from the controller.

This application call-back function is called by the Profinet stack on every IODRead request from the Profinet controller which specify an application-specific value of idx (0x0000 - 0x7fff). All other values of idx are handled internally by the Profinet stack.

The application must verify the value of idx, and that p_read_length is large enough. Further, the application must provide a pointer to the binary value in pp_read_data and the size, in bytes, of the binary value in p_read_length.

The Profinet stack does not perform any endianness conversion on the binary value.

In case of error the application should provide error information in p_result.

Return

0 on success. -1 if an error occurred.Error status if returning != 0

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • api: In: The AP identifier.

  • slot: In: The slot number.

  • subslot: In: The sub-slot number.

  • idx: In: The data record index.

  • sequence_number: In: The sequence number.

  • pp_read_data: Out: A pointer to the binary value.

  • p_read_length: InOut: The maximum (in) and actual (out) length in bytes of the binary value.

  • p_result: Out: Detailed error information.

typedef int (*pnet_write_ind)(pnet_t *net, void *arg, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t idx, uint16_t sequence_number, uint16_t write_length, const uint8_t *p_write_data, pnet_result_t *p_result)

Indication to the application that an IODWrite request was received from the controller.

This application call-back function is called by the Profinet stack on every IODWrite request from the Profinet controller which specify an application-specific value of idx (0x0000 - 0x7fff). All other values of idx are handled internally by the Profinet stack.

The application must verify the values of idx and write_length and save (copy) the binary value in p_write_data. A future IODRead must return the latest written value.

The Profinet stack does not perform any endianness conversion on the binary value.

In case of error the application should provide error information in p_result.

Return

0 on success. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • api: In: The API identifier.

  • slot: In: The slot number.

  • subslot: In: The sub-slot number.

  • idx: In: The data record index.

  • sequence_number: In: The sequence number.

  • write_length: In: The length in bytes of the binary value.

  • p_write_data: In: A pointer to the binary value.

  • p_result: Out: Detailed error information.

typedef int (*pnet_exp_module_ind)(pnet_t *net, void *arg, uint32_t api, uint16_t slot, uint32_t module_ident)

Indication to the application that a module is requested by the controller in a specific slot.

This application call-back function is called by the Profinet stack to indicate that the controller has requested the presence of a specific module, ident number module_ident, in the slot number slot.

The application must react to this by configuring itself accordingly (if possible) and call function pnet_plug_module() to configure the stack for this module.

If the wrong module ident number is plugged then the stack will accept this, but signal to the controller that a substitute module is fitted.

This function should return 0 (zero) if a valid module was plugged. Or return -1 if the application cannot handle this request.

Return

0 on success. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • api: In: The AP identifier.

  • slot: In: The slot number.

  • module_ident: In: The module ident number.

typedef int (*pnet_exp_submodule_ind)(pnet_t *net, void *arg, uint32_t api, uint16_t slot, uint16_t subslot, uint32_t module_ident, uint32_t submodule_ident, const pnet_data_cfg_t *p_exp_data)

Indication to the application that a sub-module is requested by the controller in a specific sub-slot.

This application call-back function is called by the Profinet stack to indicate that the controller has requested the presence of a specific sub-module, ident number submodule_ident, in the sub-slot number subslot, with module ident number module_ident in slot slot.

If a module has not been plugged in the slot slot then an automatic plug request is issued internally by the stack.

The application must react to this by configuring itself accordingly (if possible) and call function pnet_plug_submodule() to configure the stack with the correct input/output data sizes.

If the wrong sub-module ident number is plugged then the stack will accept this, but signal to the controller that a substitute sub-module is fitted.

This function should return 0 (zero) if a valid sub-module was plugged. Or return -1 if the application cannot handle this request.

Return

0 on success. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • api: In: The AP identifier.

  • slot: In: The slot number.

  • subslot: In: The sub-slot number.

  • module_ident: In: The module ident number.

  • submodule_ident: In: The sub-module ident number.

  • p_exp_data: In: The expected data configuration

typedef int (*pnet_new_data_status_ind)(pnet_t *net, void *arg, uint32_t arep, uint32_t crep, uint8_t changes, uint8_t data_status)

Indication to the application that the data status received from the controller has changed.

This application call-back function is called by the Profinet stack to indicate that the received data status has changed.

The application is not required by the Profinet stack to take any action. It may use this information as it wishes. The return value from this call-back function is ignored by the Profinet stack.

Return

0 on success. Other values are ignored.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • crep: In: The CREP.

  • changes: In: The changed bits in the received data status. See pnet_data_status_bits_t

  • data_status: In: Current received data status (after changes). See pnet_data_status_bits_t

typedef int (*pnet_alarm_ind)(pnet_t *net, void *arg, uint32_t arep, const pnet_alarm_argument_t *p_alarm_argument, uint16_t data_len, uint16_t data_usi, const uint8_t *p_data)

The IO-controller has sent an alarm to the device.

This functionality is used for alarms triggered by the IO-controller.

We have already sent the transport acknowledge (“TACK”) frame.

It is optional to implement this callback (assumes success), but then it would be difficult to know when to call pnet_alarm_send_ack(). Unclear what would happen if returning -1.

Return

0 on success. -1 if an error occurred.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • p_alarm_argument: In: The alarm argument (with slot, subslot, alarm_type etc)

  • data_len: In: Data length

  • data_usi: In: Alarm USI

  • p_data: In: Alarm data

typedef int (*pnet_alarm_cnf)(pnet_t *net, void *arg, uint32_t arep, const pnet_pnio_status_t *p_pnio_status)

The controller acknowledges the alarm sent previously. It is now possible to send another alarm.

This functionality is used for alarms triggered by the IO-device.

It is optional to implement this callback. The return value from this call-back function is ignored by the Profinet stack.

Return

0 on success. Other values are ignored.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • p_pnio_status: In: Detailed ACK information.

typedef int (*pnet_alarm_ack_cnf)(pnet_t *net, void *arg, uint32_t arep, int res)

The controller acknowledges the alarm ACK sent previously.

This functionality is used for alarms triggered by the IO-controller.

It is optional to implement this callback. The return value from this call-back function is ignored by the Profinet stack.

Return

0 on success. Other values are ignored.

Parameters
  • net: InOut: The p-net stack instance

  • arg: InOut: User-defined data (not used by p-net)

  • arep: In: The AREP.

  • res: In: 0 if ACK was received by the remote side. This is cnf(+). -1 if ACK was not received by the remote side. This is cnf(-).

Selected enums

enum pnet_event_values_t

The events are sent from CMDEV to the application using the TTTTTTTTTTTTTTTTTTT pnet_state_ind() call-back function.

Values:

PNET_EVENT_ABORT

The AR has been closed.

PNET_EVENT_STARTUP

A connection has been initiated.

PNET_EVENT_PRMEND

Controller has sent all write records.

PNET_EVENT_APPLRDY

Controller has acknowledged the APPL_RDY message

PNET_EVENT_DATA
enum pnet_ioxs_values_t

Values used for IOCS and IOPS.

Values:

PNET_IOXS_BAD = 0x00
PNET_IOXS_GOOD = 0x80
enum pnet_submodule_dir_t

Values used when plugging a sub-module using pnet_plug_submodule().

Values:

PNET_DIR_NO_IO = 0x00
PNET_DIR_INPUT = 0x01
PNET_DIR_OUTPUT = 0x02
PNET_DIR_IO = 0x03
enum pnet_control_command_t

CControl command codes used in the pnet_dcontrol_ind() call-back function.

Values:

PNET_CONTROL_COMMAND_PRM_BEGIN
PNET_CONTROL_COMMAND_PRM_END
PNET_CONTROL_COMMAND_APP_RDY
PNET_CONTROL_COMMAND_RELEASE
PNET_CONTROL_COMMAND_RDY_FOR_COMPANION
PNET_CONTROL_COMMAND_RDY_FOR_RTC3
enum pnet_data_status_bits_t

Data status bits used in the pnet_new_data_status_ind() call-back function.

Values:

PNET_DATA_STATUS_BIT_STATE = 0
PNET_DATA_STATUS_BIT_REDUNDANCY

0 => BACKUP, 1 => PRIMARY

PNET_DATA_STATUS_BIT_DATA_VALID

Meaning depends on STATE bit

PNET_DATA_STATUS_BIT_RESERVED_1

0 => INVALID, 1 => VALID

PNET_DATA_STATUS_BIT_PROVIDER_STATE
PNET_DATA_STATUS_BIT_STATION_PROBLEM_INDICATOR

0 => STOP, 1 => RUN

PNET_DATA_STATUS_BIT_RESERVED_2

0 => Problem detected, 1 => Normal operation

PNET_DATA_STATUS_BIT_IGNORE

0 => Evaluate data status, 1 => Ignore the data status (typically used on a frame with subframes)

enum pnet_diag_ch_prop_type_values_t

Channel size in bits.

Values:

PNET_DIAG_CH_PROP_TYPE_UNSPECIFIED = 0
PNET_DIAG_CH_PROP_TYPE_1_BIT = 1
PNET_DIAG_CH_PROP_TYPE_2_BIT = 2
PNET_DIAG_CH_PROP_TYPE_4_BIT = 3
PNET_DIAG_CH_PROP_TYPE_8_BIT = 4
PNET_DIAG_CH_PROP_TYPE_16_BIT = 5
PNET_DIAG_CH_PROP_TYPE_32_BIT = 6
PNET_DIAG_CH_PROP_TYPE_64_BIT = 7
enum pnet_diag_ch_prop_dir_values_t

Channel direction.

Values:

PNET_DIAG_CH_PROP_DIR_MANUF_SPEC = 0
PNET_DIAG_CH_PROP_DIR_INPUT = 1
PNET_DIAG_CH_PROP_DIR_OUTPUT = 2
PNET_DIAG_CH_PROP_DIR_INOUT = 3
enum pnet_diag_ch_prop_maint_values_t

Diagnosis severity.

Values:

PNET_DIAG_CH_PROP_MAINT_FAULT = 0
PNET_DIAG_CH_PROP_MAINT_REQUIRED = 1
PNET_DIAG_CH_PROP_MAINT_DEMANDED = 2
PNET_DIAG_CH_PROP_MAINT_QUALIFIED = 3

Selected typedefs

Network and device configuration.

Configuration of the stack is performed by transferring a structure in the call to pnet_init().

Along with the configuration the initial (default) values of the I&M data records are conveyed as well as the values used for sending LLDP frames.

struct pnet_im_0_t

The I&M0 data record is read-only by the controller.

This data record is mandatory.

struct pnet_im_1_t

The I&M1 data record is read-write by the controller.

This data record is optional. If this data record is supported by the application then bit 1 in the im_supported member of I&M0 shall be set.

struct pnet_im_2_t

The I&M2 data record is read-write by the controller.

This data record is optional. If this data record is supported by the application then bit 2 in the im_supported member of I&M0 shall be set.

struct pnet_im_3_t

The I&M3 data record is read-write by the controller.

This data record is optional. If this data record is supported by the application then bit 3 in the im_supported member of I&M0 shall be set.

struct pnet_im_4_t

The I&M4 data record is read-write by the controller.

Used for functional safety.

This data record is optional. If this data record is supported by the application then bit 4 in the im_supported member of I&M0 shall be set.

struct pnet_cfg_device_id_t

The device-specific vendor and device identities.

The vendor id is obtained from Profibus International.

The device id is assigned by the vendor.

struct pnet_lldp_cfg_t

LLDP configuration used by the Profinet stack.

struct pnet_cfg_t

This is all the configuration needed to use the Profinet stack.

The application must supply the values in the call to function pnet_init().

struct pnet_alarm_spec_t

Summary of all diagnosis items, sent in an alarm. Only valid for alarms attached to the Diagnosis ASE See Profinet 2.4 Services, section 7.3.1.6.5.1 Alarm Notification

struct pnet_alarm_argument_t