AM335x PROFINET Driver API Guide

NOTE  This API guide is valid only for applications upto ISDK 1.1.0.6. For higher versions, please refer to sdk/protocols/profinet_slave/Docs/AM335X_Profinet_Slave_RT_API_Guide.chm

   

= Introduction =

Profinet Driver interfaces with 3rd Party stacks to implement Profinet I/O slave on AM335x. This driver provides interfacing with Industrial Communication SubSystem(ICSS). These APIs are used for configuring and communicating with Profinet firmware. = Profinet Driver APIs =

initPNDrv
Function

Int32 initPNDrv(void);

Parameters


 * none: none
 * Return value: 0 on Success. -1 on failure

Description Initializes the Profinet Driver

Sets the Port MAC addresses.

Initialize the RTC driver.

Loads the forward and receive multicast tables.

Loads the Profinet firmware

initRtcDrv
Function

Int32 initRtcDrv(void);

Parameters


 * none: none
 * Return value: 0 on Success. -1 on failure

Description Initializes RTC driver

Initializes CPM/PPM lists

Configures the send clock cycle

Configures and initializes RTC interrupts

initLists
Function

void initLists(void);

Parameters


 * none: none
 * Return value: none

Description Initializes the CPM and PPM descriptor lists

clearList
Function

Int32 clearList(Uint8 list);

Parameters


 * list: list type, PPM or CPM, Valid values are: CPM = 0, PPM = 1
 * Return value: 0 on success, -1 on failure

Description

Clears the index of PPM or CPM list

Clears active bits and resets all data

This does not clear buffer and desc memory

setBaseClock
Function

Int32 setBaseClock(Uint16 factor);

Parameters


 * factor: clock factor, example values are:
 * 8 to set (8*31.25) 250us cycle time, (8 is minimum possible value)
 * 32 to set 1 ms cycle time
 * 128 to set 4 ms cycle time, (128 is maximum possible value)
 * Return value: 0 on success, -1 on failure

Description Sets Profinet base clock in multiples of 31.25us.

iRtcIsrSetup
Function

Int32 iRtcIsrSetup(void);

Parameters


 * none: none
 * Return value: 0 on success, -1 on failure

Description Interrupt management function

Initializes PPM/CPM/DHT interrupts

setDcpFilterStationName
Function

Int32 setDcpFilterStationName(const Uint8* dcp_name_of_station, Uint8 length_of_station_name);

Parameters


 * dcp_name_of_station: station name of the slave
 * length_of_station_name: length of the station name
 * Return value: 0 on success, -1 on failure

Description API to set the station name of slave for filtering the DCP Ident requests which are not meant for the station

registerPpmCall
Function

void registerPpmCall(icssCallBack_t callBack);

Parameters


 * callBack: Callback function pointer
 * Return value: none

Description Registers callback function required for PPM processing

Callback function

static icssCallBack_t irtPpmCall;

registerCpmCall
Function

void registerCpmCall(icssCallBack_t callBack);

Parameters


 * callBack: Callback function pointer
 * Return value: none

Description Registers callback function required for CPM processing

Callback function

static icssCallBack_t irtCpmCall;

registerStatCall
Function

void registerStatCall(icssCallBack_t callBack);

Parameters


 * callBack: Callback function pointer
 * Return value: none

Description Registers callback function required for Stats processing

Callback function

static icssCallBack_t irtStatCall;

ppmBC_IsrHandler
Function

void ppmBC_IsrHandler(void);

Parameters


 * none:
 * Return value: none

Description PPM Interrupt Service Routine

Mapped to Interrupt number 21 on ARM

Updates Statistics

Triggers the callback registered for PPM handling(irtPpmCall)

cpmBC_IsrHandler
Function

void cpmBC_IsrHandler(Uarg);

Parameters


 * none:
 * Return value: none

Description CPM Interrupt Service Routine

Mapped to Interrupt number 22 on ARM

Updates Statistics

Triggers the callback registered for CPM handling(irtCpmCall)

dht_IsrHandler
Function

void dht_IsrHandler(Uarg);

Parameters


 * none:
 * Return value: none

Description DHT Interrupt Service Routine

Triggers on status events


 * DHT expire
 * List changes

Mapped to Interrupt number 23 on ARM

Triggers the callback registered for Stat handling(irtStatCall)

getPpmBuffLock
Function

Int32 getPpmBuffLock(Uint8* pos);

Parameters


 * pos: Return pointer to descriptor position
 * Return value: 0 on Success, -1 on Failure

Description Get PPM buffer index locked by ICSS

cpmBuffLock
Function

Int32 cpmBuffLock(Uint8 pos, buffLocks buff);

Parameters


 * pos: CPM descriptor position, Valid range is : (0 to 7)
 * buff: enum buffLocks
 * Return value: 0 on Success, -1 on Failure

Description Locks CPM buffer

Enum buffLocks

typedef enum { BUFF1 = 0, BUFF2, BUFF3, NOBUFF } buffLocks;

insPpmPacket
Function

Int32 insPpmPacket(Uint32** pktAddr, Uint16 length, Uint8 buff, Uint16 reduRatio, Uint16 phase);

Parameters


 * pktAddr: Return pointer to PRU buffer address
 * length: Length of the frame in bytes
 * buff: Number of the used PRU triple buffer
 * reduRatio: Reduction ratio of the connection the message is part of, Valid range is: (1 to 512)
 * phase: Phase the message has to be sent in
 * Return value: slot number (&gt;=0) or error (&lt;0)

Description Add a new PPM into shadow list using next free entry and increment buffers

insCpmPacket
Function

Int32 insCpmPacket(Uint32** pkt, Uint16 length, Uint16 frameId, Uint16 reduRatio, Uint16 phase);

Parameters


 * pkt: Return pointer to PRU internal start of triple buffer
 * length: frame length
 * frameId: frameId value (host format, little endian)
 * reduRatio: reduction ratio for green packets, Valid range is: (1 to 512)
 * phase: Phase send value
 * Return value: slot number (&gt;=0) or error (&lt;0)

Description Add a new CPM into list and increment buffers

setARlink
Function

Int32 setARlink(Uint8 ARgroup, Uint8 PpmNum, Uint8 CpmNum);

Parameters


 * ARgroup: AR group number, Valid range is : (0 to 7)
 * PpmNum: PPM number, Valid range is : (0 to 7)
 * CpmNum: CPM number, Valid range is : (0 to 7)
 * Return value: 0 on success, -1 on failure

Description Defines AR groups

Sets the link between CPM and PPM in an AR group

One CPM can be linked to multiple PPMs in an AR group

setCpmDHT
Function

Int32 setCpmDHT(Uint16 dht, Uint8 pos);

Parameters


 * dht: data hold timeout value (lost count)
 * pos: position of CPM descriptor, Valid range is : (0 to 7)
 * Return value: 0 on success, &lt;0 on failure

Description Sets the Data hold timer timeout value for a given descriptor

getStatusEvent
Function

Int32 getStatusEvent(Uint8* eventNum, Uint8* eventType);

Parameters


 * eventNum: Return pointer of CPM/PPM number that triggered event
 * eventType: Return pointer for type of event
 * Return value: 0 on success, &lt;0 on failure

Description Get the data for status IRQ from ICSS

getPmStatus
Function

Int32 getPmStatus(Uint8 dir, Uint8 numPm);

Parameters


 * dir: PPM or CPM, Valid values are: CPM = 0, PPM = 1
 * numPm: number of PM to check
 * Return value: PM status or error (&lt;0)

PM Status 


 * 1) define RTC_PPM_OK			1
 * 2) define RTC_PPM_ERROR			0
 * 3) define RTC_CPM_RUN			1
 * 4) define RTC_CPM_FAILURE	       	0

Description Return PM status information as set by PRU

getPpmAddr
Function

Int32 getPpmAddr(Uint32** pkt, Uint8 pos, Uint8 buff);

Parameters


 * pkt: Returns pointer of packet buffer
 * pos: Slot number of the descriptor
 * buff: Number of the used PRU triple buffer
 * Return value: 0 on success, &lt;0 on failure

Description Retreives a buffer address of active descriptor required to initialize the packet data buffer

setIndex
Function

Int32 setIndex(Uint8 dir, Uint8 greenStart, Uint8 redP2Start, Uint8 greenP2Start, Uint8 greenEnd);

Parameters


 * dir: CPM or PPM, Valid values are: CPM = 0, PPM = 1
 * greenStart: Index of first Port 1 descriptor in green period
 * redP2Start: Index of first Port 2 descriptor in red period
 * greenP2Start: Index of first Port 2 descriptor in green period
 * greenEnd: Index of last descriptor of green period
 * Return value: 0 on success, &lt;0 on Failure

Description Setup index values for shadow list

CPM or PPM list is pre-sorted by period, port and time.

redStart for Port1 is 0 by definition and redEnd is equal to greenStart

getIndex
Function

Int32 getIndex(Uint8 dir, Uint8 *greenStart, Uint8 *redP2Start, Uint8 *greenP2Start, Uint8 *greenEnd);

Parameters


 * dir: CPM or PPM, Valid values: CPM = 0, PPM = 1
 * greenStart: Return pointer to first Port 1 descriptor index in green period
 * redP2Start: Return pointer to first Port 2 descriptor index in red period
 * greenP2Start: Return pointer to first Port 2 descriptor index in green period
 * greenEnd: Return pointer to last descriptor index of green period
 * Return value: 0 on success, &lt;0 if Failure

Description get index values from active list

writeDescriptor
Function

Int32 writeDescriptor(t_rtcDesc* desc, t_descList* pList);

Parameters


 * desc: Pointer to the descriptor to be inserted in the list
 * pList: References the list, the requested descriptor is part of (ppm_list, cpm_list)
 * Return value: slot number (&gt;=0) or error (&lt;0)

Description Insert a descriptor into shadow list at next free slot

readDescriptor
Function

Int32 readDescriptor(t_rtcDesc* desc, t_descList* pList, Uint8 pos, Uint8 active);

Parameters


 * desc: Returns the pointer to the requested descriptor
 * pList: References the list, the requested descriptor is part of (ppm_list, cpm_list)
 * pos: Index of the requested descriptor in the list (0,1,...,7)
 * active: Specifies if the requested descriptor is from the active list (=1, ACTIVE_LIST) or the shadow list (=0, SHADOW_LIST)
 * Return value: 0 on Success, &lt;0 on Failure

Description Read back a (valid) descriptor from active or shadow list

getShadowIndex
Function

Uint8 getShadowIndex(Uint8 lType);

Parameters


 * lType: list type, PPM or CPM, Valid values are: CPM = 0, PPM = 1
 * Return value: the current shadow index according to PRU data

Description Gets the shadow index

clearShadowList
Function

Int32 clearShadowList(Uint8 list);

Parameters


 * list: list type, PPM or CPM, Valid values are: CPM = 0, PPM = 1
 * Return value: 0 on Success, &lt;0 on Failure

Description Clear the index of PPM or CPM shadow list

The corresponding active list stays unaffected

setActiveBit
Function

Int32 setActiveBit(Uint8 list, Uint8 index, Uint8 val);

Parameters


 * list: list type, PPM or CPM, Valid values are: CPM = 0, PPM = 1
 * index: index of the descriptor in the list, Valid range is: (0 to 7)
 * val: val=1 sets and val=0 clears the active bit.
 * Return value: 0 on Success, &lt;0 on Failure

Description Change the active bit of descriptor at index in active list

toggleRtcList
Function

Int32 toggleRtcList(Uint8 list);

Parameters


 * list: list type, PPM or CPM, Valid values are: CPM = 0, PPM = 1
 * Return value: 0 on Success, &lt;0 on Failure

Description Request to switch active and shadow list

Requests a toggle of active and shadow lists, it should be answered by PRU via status IRQ.

Update CPM/PPM stats structure

Struct for CPM/PPM Statistics

typedef struct switchStats { Uint8 frameLength; Uint32* macAddr; } t_switchStats;

iRtcEnableIsr
Function

Int32 iRtcEnableIsr(void);

Parameters


 * none
 * Return value: 0

Description Enables the PN interrupts

iRtcDisableIsr
Function

Int32 iRtcDisableIsr(void);

Parameters


 * none
 * Return value: 0

Description Disables the PN interrupts = Memory Map =