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 full Doxygen documentation by running make docs in the build directory. The resulting HTML files will end up in build/html/index.html.

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.

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 state_cb(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 when you detect for example that 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. 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.

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 exp_module_cb 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 exp_submodule_cb 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, 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 IOCS) 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)

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)

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 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.

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, 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 alarm_cnf_cb before sending another alarm. This function fails if the application does not wait for the alarm_cnf_cb between sending two alarms.

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.

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

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

int pnet_alarm_send_ack(pnet_t *net, uint32_t arep, 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.

Return

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

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

  • arep: In: The AREP.

  • p_pnio_status: In: Detailed ACK status.

int pnet_diag_add(pnet_t *net, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t ch, uint16_t ch_properties, uint16_t ch_error_type, uint16_t ext_ch_error_type, uint32_t ext_ch_add_value, uint32_t qual_ch_qualifier, uint16_t usi, uint8_t *p_manuf_data)

Add a diagnosis entry.

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.

  • ch: In: The channel number

  • ch_properties: In: The channel properties.

  • ch_error_type: In: The channel error type.

  • ext_ch_error_type: In: The extended channel error type.

  • ext_ch_add_value: In: The extended channel error additional value.

  • qual_ch_qualifier: In: The qualified channel qualifier.

  • usi: In: The USI. range: 0..0x7fff for manufacturer-specific diag format. 0x8000 for standard format.

  • p_manuf_data: In: The manufacturer specific diagnosis data. (Only needed if USI <= 0x7fff).

int pnet_diag_update(pnet_t *net, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t ch, uint16_t ch_properties, uint16_t ch_error_type, uint32_t ext_ch_add_value, uint16_t usi, uint8_t *p_manuf_data)

Update a diagnosis entry.

If the USI of the item is in the manufacturer-specified range then the USI is used to identify the item. Otherwise the other parameters are used (all must match):

  • API id.

  • Slot number.

  • Sub-slot number.

  • Channel number.

  • Channel properties (the channel direction part only).

  • Channel error type.

When the item is found either the manufacturer data is updated (for USI in manufacturer-specific range) or the extended channel additional value is updated.

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.

  • ch: In: The channel number

  • ch_properties: In: The channel properties.

  • ch_error_type: In: The channel error type.

  • ext_ch_add_value: In: The extended channel error additional value.

  • usi: In: The USI. range: 0..0x7fff for manufacturer-specific diag format. 0x8000 for standard format.

  • p_manuf_data: In: The manufacturer specific diagnosis data. (Only needed if USI <= 0x7fff).

int pnet_diag_remove(pnet_t *net, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t ch, uint16_t ch_properties, uint16_t ch_error_type, uint16_t usi)

Remove a diagnosis entry.

If the USI of the item is in the manufacturer-specified range then the USI is used to identify the item. Otherwise the other parameters are used (all must match):

  • API id.

  • Slot number.

  • Sub-slot number.

  • Channel number.

  • Channel properties (the channel direction part only).

  • Channel error type.

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.

  • ch: In: The channel number

  • ch_properties: In: The channel properties.

  • ch_error_type: In: The channel error type.

  • usi: In: The USI. range: 0..0x7fff for manufacturer-specific diag format. 0x8000 for standard format.

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 (zero) 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.

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. In case of error the application should provide error information in p_result.

It is optional to implement this callback.

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_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 callback.) 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).

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)

  • 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 complianct Profinet device must have a signal LED)

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)

  • 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, 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)

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.

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.

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.

  • 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).

typedef int (*pnet_alarm_ind)(pnet_t *net, void *arg, uint32_t arep, uint32_t api, uint16_t slot, uint16_t subslot, uint16_t data_len, uint16_t data_usi, uint8_t *p_data)

The controller has sent an alarm to the device.

It is optional to implement this callback.

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 AP identifier.

  • slot: In: The slot number.

  • subslot: In: The sub-slot number.

  • data_len: In: Data length

  • data_usi: In: Alarm USI

  • p_data: InOut: Alarm data

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

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

It is optional to implement this callback.

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_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.

It is optional to implement this callback.

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.

  • res: In: 0 if ACK was received by the remote side. -1 if ACK was not received by the remote side.

Selected enums

enum pnet_event_values_t

The events are sent from CMDEV to the application using the state_cb 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.

Values:

PNET_DIR_NO_IO
PNET_DIR_INPUT
PNET_DIR_OUTPUT
PNET_DIR_IO
enum pnet_control_command_t

CControl command codes used in the dcontrol_cb 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 new_data_status_cb 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)

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.

Configuration values are taken as is. No validation is performed.

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 0 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 1 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 2 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.

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_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 information 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

Alarm and Diagnosis