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
0x0020 0x0400 0x0200 0x0800 0x1000 0x1001 0x1002 0x1003 0x2000 0x4000 0x8000 Bit 15 1 1 1 1 1 1





literal notranslate">level

: In: The amount of detail to show.

0x0010              | Show compile time options | Show CMDEV | Show logbook | Show diagnosis | Show all sessions. | Show all ARs. |     include IOCR. |     include data_descriptors. |     include IOCR and data_descriptors. | Show CFG information. | Show scheduler information. | Show I&M data. in the level parameter: 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 I&M Scheduler CMINA AR Sessions Logbook class="mi">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¶