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

AM335x Profinet Driver API Guide

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 (>=0) or error (<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 (>=0) or error (<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, <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, <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 (<0)

PM Status

#define RTC_PPM_OK			1
#define RTC_PPM_ERROR			0
#define RTC_CPM_RUN			1              
#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, <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, <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, <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 (>=0) or error (<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, <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, <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, <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, <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

L3 OCMC RAM

Usage	Size	Memory Range
Host Receive and Port Transmit Queues	48.5 KB	0x40300000 to 0x4030C1FF
CPM Receive Queues	11 KB	0x4030C200 to 0x4030EDFF
Queue Contention buffers	4.5 KB	0x4030EE00 to 0x4030FFFF

PRU0 DATA RAM

Usage	Size	Memory Range
CPM/PPM List Descriptors	384 KB	0x4A300000 to 0x4A30017F
RTC Configuration Data	292 KB	0x4A300180 to 0x4A3002A3
Reserved	92 KB	0x4A3002A4 to 0x4A3002FF
DCP Identify Filter Data	66 KB	0x4A300300 to 0x4A300341
Free Space	7 KB	0x4A300342 to 0x4A301FFF

PRU1 DATA RAM

Usage	Size	Memory Range
PPM DATA Buffers	4944 KB	0x4A302000 to 0x4A30334F
Reserved	2736KB	0x4A303350 to 0x4A303DFF
Switch Configuration Data	136 KB	0x4A303E00 to 0x4A303E87
Queue Descriptors	96 KB	0x4A303E88 to 0x4A303EE7
Reserved	24 KB	0x4A303EE8 to 0x4A303EFF
Statistics	88 KB	0x4A303F00 to 0x4A303F57
Free Space	168 KB	0x4A303F58 to 0x4A303FFF

ICSS SHARED RAM

Usage	Size	Memory Range
Host Receive and Port Transmit Queues Buffer Descriptors	6 KB	0x4A310000 to 0x4A3117FF
Queue Contention Queues Buffer Descriptors	576 KB	0x4A311800 to 0x4A311A3F
Static Receive Multicast MAC Table	250 KB	0x4A311A40 to 0x4A31B3B
Static Receive Multicast MAC Table	250 KB	0x4A31B3C to 0x4A31C35
Free Space	5 KB	0x4A31C36 to 0x4A312FFF