MODBUS Porting Layer

Detailed Description

Every platform targeted by the MODBUS stack must implemented all the functions listed below. A good start for creating a new platform is by using either the template from the directory demo/BARE if not RTOS is available or demo/BARERTOS if an RTOS is available.
All new ports should be tested using the supplied test programs. For an example on this and more instructions the module MODBUS Porting Layer Verification should be read.


Modules

 MODBUS Porting Layer Verification
 MODBUS Porting Layer (Serial)
 MODBUS Porting Layer (TCP)
 MODBUS Porting Layer (UDP)

Defines

#define INLINE   inline
#define STATIC   static
#define PR_BEGIN_EXTERN_C   extern "C" {
#define PR_END_EXTERN_C   }
#define MBM_PORT_ASSERT(x)   assert( x )
#define MBM_PORT_ENTER_CRITICAL_SECTION()
#define MBM_PORT_EXIT_CRITICAL_SECTION()
#define TRUE   ( BOOL )1
#define FALSE   ( BOOL )0
#define MBM_PORT_EVENTHDL_INVALID   NULL
#define MBM_PORT_TIMERHDL_INVALID   NULL
#define MBM_PORT_SERIALHDL_INVALID   NULL
#define MBM_PORT_TCPHDL_INVALID   NULL

Typedefs

typedef UBYTE xMBPEventType
typedef BOOL(* pbMBPTimerExpiredCB )(xMBHandle xHdl)
typedef void * xMBMPortEventHandle
typedef void * xMBMPortTimerHandle
typedef void * xMBMPortSerialHandle
typedef void * xMBMPortTCPHandle
typedef char BOOL
typedef unsigned char UBYTE
typedef char BYTE
typedef unsigned char UCHAR
typedef char CHAR
typedef unsigned short USHORT
typedef short SHORT
typedef unsigned long ULONG
typedef long LONG

Functions

eMBErrorCode eMBPTimerInit (xMBPTimerHandle *xTimerHdl, USHORT usTimeOut1ms, pbMBPTimerExpiredCB pbMBPTimerExpiredFN, xMBHandle xHdl)
void vMBPTimerClose (xMBPTimerHandle xTimerHdl)
eMBErrorCode eMBPTimerSetTimeout (xMBPTimerHandle xTimerHdl, USHORT usTimeOut1ms)
eMBErrorCode eMBPTimerStart (xMBPTimerHandle xTimerHdl)
eMBErrorCode eMBPTimerStop (xMBPTimerHandle xTimerHdl)
eMBErrorCode eMBPEventCreate (xMBPEventHandle *pxEventHdl)
eMBErrorCode eMBPEventPost (const xMBPEventHandle xEventHdl, xMBPEventType xEvent)
BOOL bMBPEventGet (const xMBPEventHandle xEventHdl, xMBPEventType *pxEvent)
void vMBPEventDelete (xMBPEventHandle xEventHdl)
void vMBPLibraryLoad (void)
void vMBPLibraryUnload (void)
void vMBPPortLog (eMBPortLogLevel eLevel, eMBPortLogFacility eModule, const CHAR *szFmt,...)
BOOL bMBPPortLogIsEnabled (eMBPortLogLevel eLevel, eMBPortLogFacility eModule)
void vMBPGetTimeStamp (xMBPTimeStamp *pTimeStamp)

Define Documentation

#define FALSE   ( BOOL )0
 

A boolean evaluating to false in an boolean C-Expression.

Examples:
AVR/demo.c.

#define INLINE   inline
 

INLINE macro to match different compiler types.

#define MBM_PORT_ASSERT (  x   )     assert( x )
 

An assertion macro.

If this function is called the port should enter its debug mode and the system should be restarted.

 
#define MBM_PORT_ENTER_CRITICAL_SECTION (   ) 
 

This macro must disable interrupts on the system.

This function disable interrupts and keeps track on the number of times it has been called. Typically it would save the processor status register on entry, disable interrupts and if it was called the first time it will save the processor status register. At every call it would increment the so called nesting counter.

#define MBM_PORT_EVENTHDL_INVALID   NULL
 

An invalid handle for an event queue.

 
#define MBM_PORT_EXIT_CRITICAL_SECTION (   ) 
 

This macro should restore the old system status.

If this function has been called the same time as the function MBM_PORT_ENTER_CRITICAL_SECTION is should restore the processor context stored when MBM_PORT_ENTER_CRITICAL_SECTION was called the first time. A typical implementation would decrement the counter and if the counter reaches zero it would restore the old value.

#define MBM_PORT_SERIALHDL_INVALID   NULL
 

An invalid handle for a serial port.

#define MBM_PORT_TCPHDL_INVALID   NULL
 

An invalid handle for a TCP instance.

#define MBM_PORT_TIMERHDL_INVALID   NULL
 

An invalid handle for a timer.

#define PR_BEGIN_EXTERN_C   extern "C" {
 

Mark functions as C code for C++ sources. Start tag.

#define PR_END_EXTERN_C   }
 

Mark functions as C code for C++ sources. End tag.

#define STATIC   static
 

STATIC macro to match different compiler types.

Examples:
AVR/demo.c.

#define TRUE   ( BOOL )1
 

A boolean evaluating to true in an boolean C-Expression.

Examples:
AVR/demo.c.

Typedef Documentation

typedef char BOOL
 

Boolean data type.

Examples:
AVR/demo.c.

typedef char BYTE
 

A byte holding value from -128 to 127.

typedef char CHAR
 

A character holding value from -128 to 127.

typedef long LONG
 

An signed long value holding values from -2147483648 to 2147483647.

typedef BOOL( * pbMBPTimerExpiredCB)(xMBHandle xHdl)
 

A callback function which should be called if the timer has expired.

Parameters:
xHdl The MODBUS stack handle passed to eMBPortTimerInit.
Returns:
The return value is only important if the RTOS can make use of any additional scheduling information. This function returns TRUE if an internal event has been generated and a context switch should be performed.

typedef short SHORT
 

An signed short value holding values from -32768 to 32767.

typedef unsigned char UBYTE
 

An unsigned byte holding value from 0 to 255.

Examples:
AVR/demo.c.

typedef unsigned char UCHAR
 

An unsigned character holding value from 0 to 255.

typedef unsigned long ULONG
 

An unsigned long value holding values from 0 to 4294967296.

typedef unsigned short USHORT
 

An unsigned short value holding values from 0 to 65535.

Examples:
AVR/demo.c.

typedef void* xMBMPortEventHandle
 

A port dependent type for an event handle.

typedef void* xMBMPortSerialHandle
 

A port dependent type for a serial handle.

typedef void* xMBMPortTCPHandle
 

A port dependent type for a TCP handle.

typedef void* xMBMPortTimerHandle
 

A port dependent type for a timer handle.

typedef UBYTE xMBPEventType
 

An abstract data type used as an interface to the event queues.

Function Documentation

BOOL bMBPEventGet (  const xMBPEventHandle  xEventHdl,
xMBPEventType *  pxEvent
) 
 

Get an event from the queue.

Parameters:
xEventHdl A valid handle created by eMBPortEventCreate.
pxEvent If the function returns TRUE the pointer is updated to hold the stored event. Otherwise it is left unchanged.
Returns:
TRUE if an event was available in the queue. Otherwise FALSE.

BOOL bMBPPortLogIsEnabled (  eMBPortLogLevel  eLevel,
eMBPortLogFacility  eModule
) 
 

Checks if a given level module is enabled. This is used to improve execution speed because if logging is not required the printf formatter is not called and a function call is avoided.

Parameters:
eLevel Severity level of log message.
eModule Module which wants to a log a message.
Returns:
TRUE if the message will be logged.

eMBErrorCode eMBPEventCreate (  xMBPEventHandle *  pxEventHdl  ) 
 

Creates a new event handler.

An event handler allows the posting of an event. At most one event is posted at once and this event can be retrieved later by calling bMBPEventGet. The function bMBPEventGet should return FALSE if no event is available.

Note:
If an RTOS is available this function should be implemented by message queues with a depth of one. If an event is posted a message should be placed in the queue. The function bMBPEventGet should try to get a message from the queue and it is allowed to block.

If no RTOS is used the function eMBPEventPost could simply place the event into a global variable. The function bMBPEventGet checks if an event has been posted and has not been processed ( Processed means it has been returned by a previous call). If no event is ready it should return FALSE. Otherwise the event is removed and the function returns TRUE.

Parameters:
pxEventHdl A pointer to an event handle. If the function returns eMBErrorCode::MB_ENOERR the value should contain a valid event handle.
Returns:
eMBErrorCode::MB_ENOERR if the event handle has been created. eMBErrorCode::MB_EINVAL if pxEventHdl was NULL. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPEventPost (  const xMBPEventHandle  xEventHdl,
xMBPEventType  xEvent
) 
 

Post a event to an event queue.

Parameters:
xEventHdl A valid event handle.
xEvent The event to post. Any previous event will be overwritten.
Returns:
eMBErrorCode::MB_ENOERR if the event has been posted. eMBErrorCode::MB_EINVAL if the handle was not valid. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPTimerInit (  xMBPTimerHandle *  xTimerHdl,
USHORT  usTimeOut1ms,
pbMBPTimerExpiredCB  pbMBPTimerExpiredFN,
xMBHandle  xHdl
) 
 

Creates a new Timer and returns a handle to this timer.

Timers are a generic instruction. If the timer has been started by a call to eMBPTimerStart a callback should be made when the timer has expired using the function pointer pbMBPTimerExpiredFN with the handle xHdl as an argument.

The following semantics are important for the implementation of the porting layer:

  • If a timer has been started and it has expired a callback should be made.
  • All timers are singleshot. Therefore it does not reenable itself.
  • It must be possible to stop an already running timer. In this case no callback should be made.
  • If a timer is closed all its resources should be released and the handle should no longer be valid.
  • Starting a timer when it is already running resets its timeout.
  • Stopping a timer multiple times has no side effects other than the disabling of the timer.
  • All timers must start disarmed.i

Parameters:
xTimerHdl A pointer to a timer handle. If the function returns eMBErrorCode::MB_ENOERR the handle should be valid.
usTimeOut1ms Timeout in milliseconds.
pbMBPTimerExpiredFN A pointer to a function.
xHdl A MODBUS handle.
Returns:
eMBErrorCode::MB_ENOERR if a new timer has been created. eMBErrorCode::MB_EINVAL if either xTimerHdl equals NULL or pbMBPTimerExpiredFN equals NULL or xHdl equals MBP_HDL_INVALID. In case no more timers can be created the function should return eMBErrorCode::MB_ENORES. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPTimerSetTimeout (  xMBPTimerHandle  xTimerHdl,
USHORT  usTimeOut1ms
) 
 

Changes the timeout for a timer.

Parameters:
xTimerHdl A valid timer handle.
usTimeOut1ms The new timeout in milliseconds.
Returns:
eMBErrorCode::MB_ENOERR if the timeout has been changed. eMBErrorCode::MB_EINVAL if the timer handle was not valid. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPTimerStart (  xMBPTimerHandle  xTimerHdl  ) 
 

Starts the timer.

When a timer has been started the timer module should perform a callback after the timeout for this timer has been elapsed or the timer has been disabled before it has expired.

Parameters:
xTimerHdl A valid timer handle.
Returns:
eMBErrorCode::MB_ENOERR if the timer has been started. eMBErrorCode::MB_EINVAL if the timer handle was not valid. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

eMBErrorCode eMBPTimerStop (  xMBPTimerHandle  xTimerHdl  ) 
 

Stops the timer.

If the timer has been stopped no callbacks should be performed.

Parameters:
xTimerHdl A valid timer handle.
Returns:
eMBErrorCode::MB_ENOERR if the timer has been stopped. eMBErrorCode::MB_EINVAL if the timer handle was not valid. All other errors should be mapped to eMBErrorCode::MB_EPORTERR.

void vMBPEventDelete (  xMBPEventHandle  xEventHdl  ) 
 

Releases the event queue.

Parameters:
xEventHdl A event handle to remove.

void vMBPGetTimeStamp (  xMBPTimeStamp *  pTimeStamp  ) 
 

Get the current timestamp.

This function must store the current implementation dependent timestamp into the variable pointed to by pTimeStamp. It must be safe for an implementation to copy this data structure into a different one, for example by using memcpy.

void vMBPLibraryLoad (  void   ) 
 

If the advanced startup/shutdown functionallity has been enabled this function is called when the first TCP or RTU/ASCII instance is created.

This functionallity can be enabled by setting the macro MBP_ADVA_STARTUP_SHUTDOWN_ENABLED to 1 in the file mbmconfig.h or mbsconfig.h.

void vMBPLibraryUnload (  void   ) 
 

If the advanced startup/shutdown functionallity has been enabled this function is called when the last TCP or RTU/ASCII has been removed.

This functionallity can be enabled by setting the macro MBP_ADVA_STARTUP_SHUTDOWN_ENABLED to 1 in the file mbmconfig.h or mbsconfig.h.

void vMBPPortLog (  eMBPortLogLevel  eLevel,
eMBPortLogFacility  eModule,
const CHAR *  szFmt,
  ...
) 
 

Log a message using using the porting layer facility.

Parameters:
eLevel Severity level of log message.
eModule Module which wants to a log a message.
szFmt printf style formatting options.

void vMBPTimerClose (  xMBPTimerHandle  xTimerHdl  ) 
 

Releases this timer.

Parameters:
xTimerHdl A timer handle. If not valid the function should do nothing.

(C) 2007 Embedded Solutions. Last updated on 14 Jun 2015.