Difference between revisions of "Platform Abstraction Layer"

From STRIDE Wiki
Jump to: navigation, search
(→‎PAL Transport (I/O) Services)
 
(47 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
The PAL, or Platform Abstraction Layer, enables the STRIDE Runtime to be platform-independent by providing a consistent interface for the STRIDE Runtime regardless of the operating system or data transport used. This interface layer is necessary given the broad variety of operating systems and data transports that exist within embedded systems today.
+
__NOTOC__
 +
The PAL, or Platform Abstraction Layer, enables the [[Runtime Reference|STRIDE Runtime]] to be platform-independent by providing a consistent interface for the STRIDE Runtime regardless of the operating system or data transport used. This interface layer is necessary given the broad variety of operating systems and data transports that exist within embedded systems today.
  
−
== PAL Concepts ==
+
A small set of functions, written according to the PAL specification, provide the interfaces between your operating system and platform transport mechanism to the STRIDE Runtime. Through the PAL, the STRIDE Runtime becomes independent of any specific platform. The PAL is designed to use standard concepts and services present in almost all operating systems and transport mechanisms. To complete a PAL, you’ll need to be familiar with concepts such as event signaling, scheduling, timers, critical section protection, memory allocation and data transfers.
 +
 
 +
The '''pal.h''' header file provided with the STRIDE Runtime contains all the function prototypes necessary for writing the PAL.
 +
 
 +
STRIDE provides fully functional implementations of the PAL for several major platforms (Windows, Linux, FreeBSD, etc.).
 +
 
 +
For a detailed description of the PAL and its interfaces, see the '''[[Platform Abstraction Layer|Platform Abstraction Layer]]''' description and the [[Media:s2sPAL.pdf|STRIDE Platform Abstraction Layer (PAL) Specification]].
 +
 
 +
= PAL Concepts =
 
This section describes the basic concepts of the PAL and the system services it must provide.
 
This section describes the basic concepts of the PAL and the system services it must provide.
  
−
=== Function Registration ===
+
== Function Registration ==
−
Typically, the STRIDE Runtime calls PAL functions; however, there are some functions
+
Typically, the STRIDE Runtime calls PAL functions; however, there are some functions in the STRIDE Runtime that need to be called by the PAL. To eliminate PAL dependencies on the STRIDE Runtime, these functions are accessed through a function registration process initiated by the STRIDE Runtime at startup. You write the registration routine called by the Runtime. This registration routine passes in the address of the STRIDE Runtime function to be registered as the input parameter, and stores the address of the STRIDE Runtime function in your own function variable, which is actually a pointer to a function. You can then call the registered function using your function pointer variable.
−
in the STRIDE Runtime that need to be called by the PAL. To eliminate PAL
+
 
−
dependencies on the STRIDE Runtime, these functions are accessed through a function
+
The registered STRIDE Runtime functions allow you to complete such tasks as delivering a received I block to the Runtime, checking the number of I-blocks the Runtime has ready to send out, or signalling the Runtime that your transport is ready for the next I-block. It is not necessary for the PAL to know the details of these Runtime functions.
−
registration process initiated by the STRIDE Runtime at startup. You write the
+
 
−
registration routine called by the Runtime. This registration routine passes in the address
+
== Task Synchronization / Event Notification ==
−
of the STRIDE Runtime function to be registered as the input parameter, and stores the
+
Unique information is required by an operating system to notify a thread of a pending event. This information can be a native OS thread id, a simple index into a table, an address to a thread control block, the address of a semaphore or one of a number of other implementations. Although each implementation may be different, a unique notifier is necessary for each thread. The STRIDE Runtime calls this unique information a Notification Identifier (NID). A thread uses a NID when waiting for a STRIDE event, and the STRIDE Runtime uses the same NID to notify the thread of a pending STRIDE event.
−
address of the STRIDE Runtime function in your own function variable, which is actually
 
−
a pointer to a function. You can then call the registered function using your function
 
−
pointer variable.
 
  
−
The registered STRIDE Runtime functions allow you to complete such tasks as
+
Support for sharing of the synchronization object among multiple applications should be ensured in case of multi-process target is enabled.
−
delivering a received I-block to the Runtime, checking the number of I-blocks the
 
−
Runtime has ready to send out, or signalling the Runtime that your transport is ready for
 
−
the next I-block. It is not necessary for the PAL to know the details of these Runtime
 
−
functions.
 
  
−
=== Event Notification ===
+
== Protection using Mutex ==
−
Unique information is required by an operating system to notify a thread of a pending
+
The STRIDE Runtime needs to protect critical and shared data structures from multiple, simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. The PAL requires implementing protection using Mutexes that can be created and, in case of multi-process target is enabled, used with a unique name by any STRIDE Runtime module or PAL itself. The STRIDE Runtime guarantees that calls to palMutexLock() will not be nested.
−
event. This information can be a simple index into a table, an address to a thread control
 
−
block, the address of a semaphore or one of a number of other implementations. Although
 
−
each implementation may be different, a unique notifier is necessary for each thread. The
 
−
STRIDE Runtime calls this unique information a Notification Identifier (NID). A thread
 
−
uses a NID when waiting for a STRIDE event, and the STRIDE Runtime uses the same
 
−
NID to notify the thread of a pending STRIDE event.
 
  
−
An additional piece of information included with the notify routine is a box ID, which is
+
== Timer Administration ==
−
the ID of the mailbox where the message is delivered.
+
The STRIDE Runtime requires that at least one timer be available. When a timer is created, a callback is registered so that the STRIDE Runtime can be notified of timer expirations.  A user parameter, provided when the timer is created, is passed to the callback when it gets called. If several timers share a callback routine, this user parameter can be used to identify which timer expired. The STRIDE Runtime can also stop, start and delete timers.
  
−
=== Critical Data Protection ===
+
Because the STRIDE Runtime also has the need to timestamp trace log data, a routine that returns the system time, palGetTime(), is also part of the PAL. This routine is not associated with timers.  
−
The STRIDE Runtime needs to protect critical data structures from multiple,
 
−
simultaneous accesses. The specific method of protection is not dictated to the PAL. The
 
−
PAL requires that when one thread calls a STRIDE function which in turn calls
 
−
palProtect(), and another thread calls a STRIDE function which also calls palProtect();
 
−
the second thread is preempted until the first thread’s STRIDE function calls
 
−
palUnprotect(). Once palUnprotect() is called, the second thread can be rescheduled
 
−
and continue. In addition, the STRIDE Runtime guarantees that calls to palProtect() will
 
−
not be nested.
 
  
−
=== Timer Administration ===
+
== Memory Allocation ==
−
The STRIDE Runtime requires that at least one timer be available. When a timer is
+
The STRIDE Runtime dynamically allocates memory for messages and trace log storage. The Runtime uses palMemAlloc() and palMemFree() to allocate memory dynamically and then return it to the system.
−
created, a callback is registered so that the STRIDE Runtime can be notified of timer
 
−
expirations. A user parameter, provided when the timer is created, is passed to the
 
−
callback when it gets called. If several timers share a callback routine, this user parameter
 
−
can be used to identify which timer expired. The STRIDE Runtime can also stop, start
 
−
and delete timers.
 
  
−
Because the STRIDE Runtime also has the need to timestamp trace log data, a routine
+
The Runtime uses palMemSegmentOpen() and palMemSegmentClose() to create, open and close memory segments. In case of single process target, these routines can simply allocate dynamic memory as in normal memory allocation routines.
−
that returns the system time, PalGetTime(), is also part of the PAL. This routine is not
 
−
associated with timers.
 
  
−
=== Memory Allocation ===
+
To support multi-process target, the STRIDE Runtime requires dynamic and configurable memory allocated through palMemAlloc() and static internal memory allocated directly through palMemSegmentOpen() to be shared memory.
−
The STRIDE Runtime dynamically allocates memory for messages and trace log storage.
 
−
The Runtime uses palMemAlloc() and palMemFree() to allocate memory dynamically
 
−
and then return it to the system.
 
  
−
=== Transport Services ===
+
In case of multi-process target, palMemAlloc() and palMemFree() routines can simply use the STRIDE Runtime’s Memory Management module ''srMem'', which is in turn dependent on palMemSegmentOpen() and palMemSegmentClose() routines.
−
The PAL transport routines are needed to transfer I-blocks (STRIDE data packets) into
 
−
and out of the STRIDE Runtime on your target platform. These routines handle the
 
−
buffering and transferring of data to and from your transport mechanism. The PAL also
 
−
contains registration routines that allow for STRIDE Runtime routines to be called by the
 
−
PAL.
 
  
−
The palOut() routine enables the STRIDE Runtime to transfer I-blocks to your transport.
+
== Transport Services ==
−
The STRIDE Runtime calls the palOut() routine whenever it needs to send out an Iblock.
+
The PAL transport routines are needed to transfer I-blocks (STRIDE data packets) into and out of the STRIDE Runtime on your target platform. These routines handle the buffering and transferring of data to and from your transport mechanism. The PAL also contains registration routines that allow for STRIDE Runtime routines to be called by the PAL.
−
Your transport calls the routine registered with the palOutRdyReg() routine when the
 
−
transport is ready for the next I-block to be transmitted. The STRIDE Runtime will not
 
−
call the palOut() routine until you call the registered function. In this way, you can
 
−
control the flow of transmitted I-blocks.
 
  
−
When a complete I-block has been received by your transport, the routine registered with
+
The palOut() routine enables the STRIDE Runtime to transfer I-blocks to your transport. The STRIDE Runtime calls the palOut() routine whenever it needs to send out an I-block.
−
the palInReg() routine should be calle to put the received I-block into the STRIDE
 
−
Runtime.
 
  
−
In some cases it is useful to know when the transmit path is not being requested. Your
+
Your transport calls the routine registered with the palOutRdyReg() routine when the transport is ready for the next I-block to be transmitted. The STRIDE Runtime will not call the palOut() routine until you call the registered function. In this way, you can control the flow of transmitted I-blocks.
−
transport mechanism can check the number of I-blocks the STRIDE Runtime has ready
+
When a complete I-block has been received by your transport, the routine registered with the palInReg() routine should be called to put the received I-block into the STRIDE Runtime.
−
for transmission by calling the routine registered with the palOutPndReg() routine.
 
  
−
=== Host Services ===
+
In some cases it is useful to know when the transmit path is not being requested. Your transport mechanism can check the number of I-blocks the STRIDE Runtime has ready for transmission by calling the routine registered with the palOutPndReg() routine.  
−
The PAL also provides a way for the STRIDE Runtime to support your transport protocol
 
−
on the desktop. A Windows® DLL linked to STRIDE Studio enables these host
 
−
services. The DLL allows your data to be received and transmitted using your transport
 
  
−
== PAL Organization ==
+
= PAL Organization =
  
 
This section explains the two categories of PAL services that support the STRIDE Runtime, as
 
This section explains the two categories of PAL services that support the STRIDE Runtime, as
−
well as the files used to implement these services on your target.
+
well as the files used to implement these services on your target. The '''pal.h''' header file provided with the STRIDE installation contains all the function prototypes.
  
−
=== PAL Services ===
+
== PAL Services ==
 
The PAL services include the following:
 
The PAL services include the following:
 
* Operating System (OS) Services
 
* Operating System (OS) Services
 
* Input/Output (IO) Services
 
* Input/Output (IO) Services
  
−
=== PAL Operating System Services ===
+
== PAL Operating System Services ==
−
The PAL Operating System (OS) Services are the routines that enable the STRIDE
+
The PAL Operating System (OS) Services are the routines that enable the STRIDE Runtime to work with the operating system on your target platform. In order to write your PAL OS services you must have detailed knowledge of how your operating system handles thread synchronization, timers, mutexes, dynamic memory, shared memory, and notification. The PAL OS services make the features of your operating system available to the STRIDE Runtime.
−
Runtime to work with the operating system on your target platform. In order to write your
 
−
PAL OS services you must have detailed knowledge of how your operating system
 
−
handles thread synchronization, timers, critical sections, dynamic memory, and
 
−
notification. The PAL OS services make the features of your operating system available
 
−
to the STRIDE Runtime.  All of the functions described here must be fully implemented in your PAL.
 
  
 
{|class="wikitable" border="2" style="margin:1em auto 1em"  
 
{|class="wikitable" border="2" style="margin:1em auto 1em"  
Line 121: Line 79:
 
|-
 
|-
 
| palNotify || Signal a thread that an event is pending  
 
| palNotify || Signal a thread that an event is pending  
 +
|-
 +
| palGetThreadId || Return current thread Id
 +
|-
 +
| palGetProcessId || Return current process Id
 +
|-
 +
| palSleep || Suspend the execution of the current thread
 
|-
 
|-
 
|colspan="2" | '''Timers'''
 
|colspan="2" | '''Timers'''
 
|-
 
|-
−
| palTimerCreate || Create a timer  
+
| palCreateTimer || Create a timer  
 
|-
 
|-
−
| palTimerDelete || Delete a timer  
+
| palDeleteTimer || Delete a timer  
 
|-
 
|-
−
| palTimerStart || Start a timer  
+
| palStartTimer || Start a timer  
 
|-
 
|-
−
| palTimerStop || Stop a timer  
+
| palStopTimer || Stop a timer  
 
|-
 
|-
 
| palGetTime || Return system time (e.g., tick count)  
 
| palGetTime || Return system time (e.g., tick count)  
 
|-
 
|-
−
|colspan="2" | '''Critical Section'''
+
|colspan="2" | '''Mutex'''
 +
|-
 +
| palMutexInit || Initialize a mutex object
 +
|-
 +
| palMutexDestroy || Destroy a mutex object
 
|-
 
|-
−
| palProtect || Begin critical section
+
| palMutexLock || Lock a mutex object
 
|-
 
|-
−
| palUnprotect || End critical section
+
| palMutexUnlock || Unlock a mutex object
 
|-
 
|-
−
|colspan="2" | '''Memory'''
+
|colspan="2" | '''Memory Management'''
 
|-
 
|-
−
| palMemAlloc || Allocate a block of dynamic memory  
+
| palMemAlloc || Allocate a block of dynamic memory
 
|-
 
|-
−
| palMemFree || Free a block of dynamic memory  
+
| palMemFree || Free a block of dynamic memory
 +
|-
 +
| palMemSegmentOpen || Create/open memory segments
 +
|-
 +
| palMemSegmentClose || Close memory segments
 
|}
 
|}
  
−
=== PAL Input/Output Services ===
+
== PAL Input/Output Services ==
 
The PAL Input/Output (IO) Services are the routines that enable the STRIDE Runtime to
 
The PAL Input/Output (IO) Services are the routines that enable the STRIDE Runtime to
 
work with different data transport mechanisms. These routines enable your transport to
 
work with different data transport mechanisms. These routines enable your transport to
Line 153: Line 125:
  
 
The IO services have also been defined to allow the target platform to control how
 
The IO services have also been defined to allow the target platform to control how
−
memory is managed and the rate of data exchange. See Appendix A beginning on page
+
memory is managed and the rate of data exchange.  
−
121 for definitions of the header file functions
 
−
 
 
  
 
{|class="wikitable" border="2" style="margin:1em auto 1em"  
 
{|class="wikitable" border="2" style="margin:1em auto 1em"  
Line 162: Line 132:
 
|colspan="2" | '''Transmit'''
 
|colspan="2" | '''Transmit'''
 
|-
 
|-
−
| PalOutPndReg || Query the current output queue of the Runtime
+
| palOutPndReg || Registers a callback to query the current output queue of the Runtime
 
|-
 
|-
−
| PalOutRdyReg || Identify the transport as ready to receive data  
+
| palOutRdyReg || Registers a callback to identify the transport as ready to receive data  
 
|-
 
|-
−
| PalOut || Send data to the host platform
+
| palOut || Send data to the host platform
 
|-
 
|-
 
|colspan="2" | '''Receive'''
 
|colspan="2" | '''Receive'''
 
|-
 
|-
−
| PalInReg || Data extracted from the transport and identified for the STRIDE Runtime
+
| palInReg || Registers a callback to process the data extracted from the transport and identified for the STRIDE Runtime
 
|}
 
|}
  
−
== Integrating the PAL ==
+
= Integrating the PAL =
  
−
=== PAL Operating System (OS) Services ===
+
== PAL Operating System (OS) Services ==
 
The '''[[Platform Abstraction Layer|PAL]]''' OS Services provide the glue between the STRIDE Runtime and the Target Operating System. The services it must provide are:
 
The '''[[Platform Abstraction Layer|PAL]]''' OS Services provide the glue between the STRIDE Runtime and the Target Operating System. The services it must provide are:
−
* Task protection and synchronization (e.g. semaphores)
+
* Task protection and synchronization (e.g. mutexes)
 
* Periodic Timers
 
* Periodic Timers
 
* Get Time Stamp
 
* Get Time Stamp
 
* Memory Management
 
* Memory Management
−
By convention, these services are implemented in a file called palOS.c.
+
By convention, these services are implemented in a file called ''palOS.c''.
−
 
 
−
=== PAL Transport (I/O) Services ===
 
−
The [[Integrating STRIDE#The_Host_Transport|Host Transport]] implement the host peer of the I/O services between the Host and Target. Most of the pre-packaged PALs below provide both a serial and a TCP/IP transport.
 
−
 
 
−
On the Target side, the Transport is usually implemented in file palIO.c.
 
  
−
On the Host side, STRIDE Studio provides menus and automation methods to manage your target connection.
+
== PAL Transport (I/O) Services ==
 +
The PAL Transport Services implement the target peer of the I/O services between the Host and Target. By convention, these services are implemented in a file called ''palIO.c''.  
  
−
;What about USB?: S2 does not yet provide a native USB transport. If you wish to use one of our pre-packaged transports, then the USB can either be used to emulate a serial (COM) port, or can be used with TCP/IP by installing and using USBNet. USBNet is open software for Linux and Windows that permits TCP/IP connections over USB.  Google "USBNet" to locate a driver for your systems.
+
The pre-packaged PALs in the [[Posix SDK]] and [[Windows SDK]] provide both a Serial and a TCP/IP transport.
−
;What if I need a custom transport?: A custom transport can be readily written to your specific needs. Please refer to the ''STRIDE Host Transport Specification'' document that is installed with STRIDE for information on creating custom Transport DLLs for the host.  Your PAL implementation will need to implement the target side of the custom communication.  More information on the Transport Wizard can be found in the ''STRIDE Developer's Guide'' in Online Help.
 
  
−
=== Using a Pre-Packaged PAL ===
+
;What about USB?: S2 does not yet provide a native USB transport. If you wish to use one of our prepackaged transports, then the  USB can either be used to emulate a serial (COM) port, or can be used with TCP/IP by installing and using USBNet. USBNet is open software for Linux and Windows that permits TCP/IP connections over USB. Google "USBNet" to locate a driver for your systems.
−
S2 can provide a ready made PAL for many common operating systems. Most contain support for both a serial and a TCP/IP transport. Select the optional '''runtime''' section when installing STRIDE to get the currently supported PALs installed on your machine, or [http://www.s2technologies.com/contact.html contact us] for help in obtaining a PAL for other platforms.
 
  
−
=== Creating your own PAL ===
+
;What if I need a custom transport?: A custom transport can be implemented. Your PAL implementation will need to implement the target side of the custom communication.
−
The PAL enables STRIDE to be completely agnostic to the underlying operating system and hardware.  In fact, an operating system is not really required, so long as the PAL can provide the needed services.
 
  
−
If there is no pre-packaged PAL for your system, you can use an existing one as a starting point, or even write a new one from scratch. Past experience has shown that a PAL can usually be implemented in about two days.
+
== PAL Resource Requirements ==
−
 
 
−
More information on creating a custom PAL, including a custom Transport can be found in the Online Help and in the ''Platform Abstraction Layer (PAL) Specification'' which can be found in C:\STRIDE\doc\s2sPAL.pdf.  S2's System's Engineers are also available to assist you with this task.
 
−
 
 
−
=== PAL Resource Requirements ===
 
 
Most PALs require a reader task to monitor the Transport input data stream.
 
Most PALs require a reader task to monitor the Transport input data stream.
  
 
PAL memory usage is limited to a few dozen bytes for table and control block storage.  The size of I/O buffers used by the reader task are Transport dependent but are usually in the 8KB range.
 
PAL memory usage is limited to a few dozen bytes for table and control block storage.  The size of I/O buffers used by the reader task are Transport dependent but are usually in the 8KB range.
  
−
=== PAL Initialization ===
+
There is no "formal" mechanism required for initializing the PAL. That is, an initialization function is not required by the STRIDE Runtime or IM.  In addition good practices require releasing resources on application exit. However, over time the convention of providing ''palInit()'' and ''palUninit()'' functions has developed. All of the Pre-Packaged PAL use this convention and their ''palInit()'' function must be called before any other STRIDE Runtime function and ''palUninit()'' on application shutdown.
−
There is no "formal" mechanism required for initializing the PAL. That is, an initialization function is not required by the STRIDE Runtime or IM.  However, over time the convention of providing a ''palInit()'' function has developed. All of the Pre-Packaged PAL use this convention and their ''palInit()'' function must be called before any other STRIDE Runtime function.
 
−
 
 
−
If you roll your own PAL, it is recommended that you maintain this convention.
 
−
 
 
−
[[Category: Deploying STRIDE]]
 
−
[[Category:STRIDE Runtime]]
 

Latest revision as of 12:56, 10 December 2020

The PAL, or Platform Abstraction Layer, enables the STRIDE Runtime to be platform-independent by providing a consistent interface for the STRIDE Runtime regardless of the operating system or data transport used. This interface layer is necessary given the broad variety of operating systems and data transports that exist within embedded systems today.

A small set of functions, written according to the PAL specification, provide the interfaces between your operating system and platform transport mechanism to the STRIDE Runtime. Through the PAL, the STRIDE Runtime becomes independent of any specific platform. The PAL is designed to use standard concepts and services present in almost all operating systems and transport mechanisms. To complete a PAL, you’ll need to be familiar with concepts such as event signaling, scheduling, timers, critical section protection, memory allocation and data transfers.

The pal.h header file provided with the STRIDE Runtime contains all the function prototypes necessary for writing the PAL.

STRIDE provides fully functional implementations of the PAL for several major platforms (Windows, Linux, FreeBSD, etc.).

For a detailed description of the PAL and its interfaces, see the Platform Abstraction Layer description and the STRIDE Platform Abstraction Layer (PAL) Specification.

PAL Concepts

This section describes the basic concepts of the PAL and the system services it must provide.

Function Registration

Typically, the STRIDE Runtime calls PAL functions; however, there are some functions in the STRIDE Runtime that need to be called by the PAL. To eliminate PAL dependencies on the STRIDE Runtime, these functions are accessed through a function registration process initiated by the STRIDE Runtime at startup. You write the registration routine called by the Runtime. This registration routine passes in the address of the STRIDE Runtime function to be registered as the input parameter, and stores the address of the STRIDE Runtime function in your own function variable, which is actually a pointer to a function. You can then call the registered function using your function pointer variable.

The registered STRIDE Runtime functions allow you to complete such tasks as delivering a received I block to the Runtime, checking the number of I-blocks the Runtime has ready to send out, or signalling the Runtime that your transport is ready for the next I-block. It is not necessary for the PAL to know the details of these Runtime functions.

Task Synchronization / Event Notification

Unique information is required by an operating system to notify a thread of a pending event. This information can be a native OS thread id, a simple index into a table, an address to a thread control block, the address of a semaphore or one of a number of other implementations. Although each implementation may be different, a unique notifier is necessary for each thread. The STRIDE Runtime calls this unique information a Notification Identifier (NID). A thread uses a NID when waiting for a STRIDE event, and the STRIDE Runtime uses the same NID to notify the thread of a pending STRIDE event.

Support for sharing of the synchronization object among multiple applications should be ensured in case of multi-process target is enabled.

Protection using Mutex

The STRIDE Runtime needs to protect critical and shared data structures from multiple, simultaneous accesses by multiple threads and, in case of multi-process target is enabled, by multiple applications. The PAL requires implementing protection using Mutexes that can be created and, in case of multi-process target is enabled, used with a unique name by any STRIDE Runtime module or PAL itself. The STRIDE Runtime guarantees that calls to palMutexLock() will not be nested.

Timer Administration

The STRIDE Runtime requires that at least one timer be available. When a timer is created, a callback is registered so that the STRIDE Runtime can be notified of timer expirations. A user parameter, provided when the timer is created, is passed to the callback when it gets called. If several timers share a callback routine, this user parameter can be used to identify which timer expired. The STRIDE Runtime can also stop, start and delete timers.

Because the STRIDE Runtime also has the need to timestamp trace log data, a routine that returns the system time, palGetTime(), is also part of the PAL. This routine is not associated with timers.

Memory Allocation

The STRIDE Runtime dynamically allocates memory for messages and trace log storage. The Runtime uses palMemAlloc() and palMemFree() to allocate memory dynamically and then return it to the system.

The Runtime uses palMemSegmentOpen() and palMemSegmentClose() to create, open and close memory segments. In case of single process target, these routines can simply allocate dynamic memory as in normal memory allocation routines.

To support multi-process target, the STRIDE Runtime requires dynamic and configurable memory allocated through palMemAlloc() and static internal memory allocated directly through palMemSegmentOpen() to be shared memory.

In case of multi-process target, palMemAlloc() and palMemFree() routines can simply use the STRIDE Runtime’s Memory Management module srMem, which is in turn dependent on palMemSegmentOpen() and palMemSegmentClose() routines.

Transport Services

The PAL transport routines are needed to transfer I-blocks (STRIDE data packets) into and out of the STRIDE Runtime on your target platform. These routines handle the buffering and transferring of data to and from your transport mechanism. The PAL also contains registration routines that allow for STRIDE Runtime routines to be called by the PAL.

The palOut() routine enables the STRIDE Runtime to transfer I-blocks to your transport. The STRIDE Runtime calls the palOut() routine whenever it needs to send out an I-block.

Your transport calls the routine registered with the palOutRdyReg() routine when the transport is ready for the next I-block to be transmitted. The STRIDE Runtime will not call the palOut() routine until you call the registered function. In this way, you can control the flow of transmitted I-blocks. When a complete I-block has been received by your transport, the routine registered with the palInReg() routine should be called to put the received I-block into the STRIDE Runtime.

In some cases it is useful to know when the transmit path is not being requested. Your transport mechanism can check the number of I-blocks the STRIDE Runtime has ready for transmission by calling the routine registered with the palOutPndReg() routine.

PAL Organization

This section explains the two categories of PAL services that support the STRIDE Runtime, as well as the files used to implement these services on your target. The pal.h header file provided with the STRIDE installation contains all the function prototypes.

PAL Services

The PAL services include the following:

  • Operating System (OS) Services
  • Input/Output (IO) Services

PAL Operating System Services

The PAL Operating System (OS) Services are the routines that enable the STRIDE Runtime to work with the operating system on your target platform. In order to write your PAL OS services you must have detailed knowledge of how your operating system handles thread synchronization, timers, mutexes, dynamic memory, shared memory, and notification. The PAL OS services make the features of your operating system available to the STRIDE Runtime.

Function Name Description
Synchronization
palCreateNID Create a Notification Identifier (NID)
palDeleteNID Delete a Notification Identifier (NID)
palCreateRFCProxyNID Create the RFC Proxy Notification Identifier (NID)
palDeleteRFCProxyNID Delete the RFC Proxy Notification Identifier (NID)
palWait Wait for an event
palNotify Signal a thread that an event is pending
palGetThreadId Return current thread Id
palGetProcessId Return current process Id
palSleep Suspend the execution of the current thread
Timers
palCreateTimer Create a timer
palDeleteTimer Delete a timer
palStartTimer Start a timer
palStopTimer Stop a timer
palGetTime Return system time (e.g., tick count)
Mutex
palMutexInit Initialize a mutex object
palMutexDestroy Destroy a mutex object
palMutexLock Lock a mutex object
palMutexUnlock Unlock a mutex object
Memory Management
palMemAlloc Allocate a block of dynamic memory
palMemFree Free a block of dynamic memory
palMemSegmentOpen Create/open memory segments
palMemSegmentClose Close memory segments

PAL Input/Output Services

The PAL Input/Output (IO) Services are the routines that enable the STRIDE Runtime to work with different data transport mechanisms. These routines enable your transport to send and receive data between the host and the target.

The IO services have also been defined to allow the target platform to control how memory is managed and the rate of data exchange.

Function Name Description
Transmit
palOutPndReg Registers a callback to query the current output queue of the Runtime
palOutRdyReg Registers a callback to identify the transport as ready to receive data
palOut Send data to the host platform
Receive
palInReg Registers a callback to process the data extracted from the transport and identified for the STRIDE Runtime

Integrating the PAL

PAL Operating System (OS) Services

The PAL OS Services provide the glue between the STRIDE Runtime and the Target Operating System. The services it must provide are:

  • Task protection and synchronization (e.g. mutexes)
  • Periodic Timers
  • Get Time Stamp
  • Memory Management

By convention, these services are implemented in a file called palOS.c.

PAL Transport (I/O) Services

The PAL Transport Services implement the target peer of the I/O services between the Host and Target. By convention, these services are implemented in a file called palIO.c.

The pre-packaged PALs in the Posix SDK and Windows SDK provide both a Serial and a TCP/IP transport.

What about USB?
S2 does not yet provide a native USB transport. If you wish to use one of our prepackaged transports, then the USB can either be used to emulate a serial (COM) port, or can be used with TCP/IP by installing and using USBNet. USBNet is open software for Linux and Windows that permits TCP/IP connections over USB. Google "USBNet" to locate a driver for your systems.
What if I need a custom transport?
A custom transport can be implemented. Your PAL implementation will need to implement the target side of the custom communication.

PAL Resource Requirements

Most PALs require a reader task to monitor the Transport input data stream.

PAL memory usage is limited to a few dozen bytes for table and control block storage. The size of I/O buffers used by the reader task are Transport dependent but are usually in the 8KB range.

There is no "formal" mechanism required for initializing the PAL. That is, an initialization function is not required by the STRIDE Runtime or IM. In addition good practices require releasing resources on application exit. However, over time the convention of providing palInit() and palUninit() functions has developed. All of the Pre-Packaged PAL use this convention and their palInit() function must be called before any other STRIDE Runtime function and palUninit() on application shutdown.

Retrieved from "https://www.stridewiki.com/index.php?title=Platform_Abstraction_Layer&oldid=14723"