Вы находитесь на странице: 1из 9

Library Description:

CoDeSys V 3.x
SysMem.library

Document Version 1.0


libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH page 1 of 10


SysMem_V3x_E.doc
Library SysMem.library

CONTENT

1 OVERVIEW 4

2 LIBRARY MODULES 5
2.1 SysMemAllocArea 5
2.2 SysMemAllocCode 5
2.3 SysMemAllocData 5
2.4 SysMemCmp 6
2.5 SysMemCpy 6
2.6 SysMemForceSwap 6
2.7 SysMemFreeArea 7
2.8 SysMemFreeCode 7
2.9 SysMemFreeData 7
2.10 SysMemIsValidPointer 8
2.11 SysMemMove 8
2.12 SysMemReallocData 8
2.13 SysMemSet 9
2.14 SysMemSwap 9

CHANGE HISTORY 10
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH page 3 of 10


SysMem_V3x_E.doc
Library SysMem.library

1 Overview

Note: It depends on the target system, which system libraries can be used in the application program.

This library conduces to memory management. Provided that the library functions are
supported by the target system they can be used to allocate or release memory, to define or
compare memory spaces, to copy the content of one memory to another or to swap. The
processing is synchronous.

The following functions are available:

SysMemAllocArea
SysMemAllocCode
SysMemAllocData
SysMemCmp
SysMemCpy
SysMemForceSwap
SysMemFreeArea
SysMemFreeCode
SysMemFreeData
SysMemIsValidPointer
SysMemMove
SysMemReallocData
SysMemSet
SysMemSwap
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH page 4 of 10


SysMem_V3x_E.doc
Library SysMem.library

2 Library Modules

2.1 SysMemAllocArea
This function dynamically allocates a memory area for an application. Therefor, the
component requesting memory has to be indicated as well as the required category and size
of memory.

The return of type POINTER TO BYTE is a pointer to the memory space reserved. In case of
the requested memory not being available, the NULL pointer will be returned. Therefore one
should always check the return even in case of small memory amount requested!
Input variable Data type Description

szComponent POINTER TO Pointer to string being assigned to name of


STRING component that is requiring memory
usType WORD Category of memory space, e.g. PERSISTENT
udiSize UDINT Number of bytes to be allocated
pResult PONTER TO UDINT Pointer to error code; see document "Runtime Error
Codes"; (may be NULL)

2.2 SysMemAllocCode
This function allocates memory space for code, wherein the code is executable. Therefore,
function SysMemAllocCode is mainly helpful for computer architectures that prevent the
default memory from executing of code. In addition to the memory size required one has to
indicate the component that is requesting memory.

The return of type POINTER TO BYTE is a pointer to the memory space reserved. In case of
the requested memory not being available, the NULL pointer will be returned. Therefore one
should always check the return even in case of small memory amount requested!
Input variable Data type Description

szComponent POINTER TO Pointer to string being assigned to name of


STRING component that is requiring memory
udiSize UDINT Number of bytes to be allocated
pResult PONTER TO UDINT Pointer to error code; see document "Runtime Error
Codes"; (may be NULL)

2.3 SysMemAllocData
This function dynamically allocates data memory for an application. Therefor, the component
requesting memory has to be indicated as well as the required category and size of memory.

The return of type POINTER TO BYTE is a pointer to the memory space reserved. In case of
the requested memory not being available, the NULL pointer will be returned. Therefore one
should always check the return even in case of small memory amount requested!
libdoc_e.dot / V1.0

Input variable Data type Description

szComponent POINTER TO Pointer to string being assigned to name of


STRING component that is requiring memory
udiSize UDINT Number of bytes to be allocated

3S - Smart Software Solutions GmbH page 5 of 10


SysMem_V3x_E.doc
Library SysMem.library

pResult PONTER TO UDINT Pointer to error code; see document "Runtime Error
Codes"; (may be NULL)

2.4 SysMemCmp
By use of this function the content of two memory areas (buffer 1 and buffer 2) can be
compared.

The return of type DINT equals 0, if the content is identical. Otherwise, the function will return
a value unlike 0.
Input variable Data type Description

pBuffer1 POINTER TO BYTE Address of first memory area (buffer 1)


pBuffer2 POINTER TO BYTE Address of second memory area (buffer 2)
udiCount UDINT Number of bytes to be compared

2.5 SysMemCpy
By use of this function a specified number of location is copied from one memory space to
another. In difference to SysMemMove (2.11) copying is only possible on non-cohesive
memory areas.

The return of type POINTER TO BYTE is a pointer to the address of the target memory.
Input variable Data type Description

pDest POINTER TO BYTE Pointer to memory address to be copied to (target)


pSrc POINTER TO BYTE Pointer to memory address to be copied from (source)
udiCount UDINT Number of bytes to be copied

2.6 SysMemForceSwap
This function serves to swap data within memory areas. It is mainly used to convert data from
Intel byte order to Motorola byte order or vice versa.

In difference to SysMemSwap (2.14) the function SysMemForceSwap does not care for the
target system used!

The return of type DINT equals

-1, if udiSize was assigned to an invalid value.


a value >0, reflecting the number of bytes swapped. In particular: return 1, if buffer is
of type Motorola and function has been called with pbyBuffer =NULL
Input variable Data type Description

pbyBuffer POINTER TO BYTE Pointer to address of memory area to be swapped;


the function being called with NULL allows to check
which order is selected
libdoc_e.dot / V1.0

udiSize UDINT Number of positions forming a unit to be swapped;


valid: 2,4,8
udiCount UDINT Number of positions forming a unit to be swapped;
valid: 2,4,8

3S - Smart Software Solutions GmbH page 6 of 10


SysMem_V3x_E.doc
Library SysMem.library

2.7 SysMemFreeArea
This function serves to release (deallocate) a memory area having been allocated by
SysMemAllocArea. Calling this function one has to indicate the name of the component
having requested this memory area originally as well as the pointer to the associated memory
address.

The return is an error code indicating success or failure of the operation (see document
"Runtime Error Codes").
Input variable Data type Description

szComponent POINTER TO Pointer to string variable being assigned to the name


STRING of the component that originally had requested the
memory
pMemory POINTER TO BYTE Pointer to address of memory space to be released

2.8 SysMemFreeCode
This function serves to release (deallocate) a code memory area having been allocated by
SysMemAllocCode.

The return is an error code indicating success or failure of the operation (see document
"Runtime Error Codes").
Input variable Data type Description

szComponent POINTER TO Pointer to string variable being assigned to the name


STRING of the component that originally had requested the
memory
pMemory POINTER TO BYTE Pointer to address of memory space to be released

2.9 SysMemFreeData
This function serves to release (deallocate) a data memory area having been allocated by
SysMemAllocData.

The return is an error code indicating success or failure of the operation (see document
"Runtime Error Codes").
Input variable Data type Description

szComponent POINTER TO Pointer to string variable being assigned to the name


STRING of the component that originally had requested the
memory
pMemory POINTER TO BYTE Pointer to address of memory space to be released
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH page 7 of 10


SysMem_V3x_E.doc
Library SysMem.library

2.10 SysMemIsValidPointer
This function checks if a pointer is assigned to a valid memory address.

The return is an error code indicating success or failure of the operation (see document
"Runtime Error Codes").
Input variable Data type Description

ptr POINTER TO BYTE Pointer to memory address to be checked


udiSize UDINT Size (number of bytes) of memory to be checked
bWrite BOOL FALSE: memory space is tested for read access.
TRUE: memory space is tested for write access.

2.11 SysMemMove
This function serves to copy the content of one memory area (source) to another (target).
Calling this function one has to transmit to pointers pointing to the address of source and
target memory.

In difference to SysMemCpy (2.5) the memory spaces of source and target may belong to a
cohesive memory area and even overlap.

The return of type UDINT is the address of the target memory.


Input variable Data type Description

pDest POINTER TO BYTE Pointer to memory address to be copied to (target)


pSrc POINTER TO BYTE Pointer to memory address to be copied from (source)
udiCount UDINT Number of bytes to be copied

2.12 SysMemReallocData
By use of this function the size of a memory block can be modified (reallocation). Therefor a
pointer on the memory block to be reallocated is passed to the function. The content of the
memory block will not be modified.

If the requested memory size cannot made available at the same place (address) , the
function will allocate new memory space, copy the original content to the new memory and
release the old one.

The return is an error code indicating success or failure of the operation (see document
"Runtime Error Codes").
Input variable Data type Description

szComponent POINTER TO Pointer to string variable being assigned to the name


STRING of the component that originally had requested the
memory
pMemory POINTER TO BYTE Pointer to memory address to be reallocated
libdoc_e.dot / V1.0

udiSize UDINT Required Size of memory (in bytes).


pResult PONTER TO UDINT Pointer to error code; (may be NULL, if no memory is
available)

3S - Smart Software Solutions GmbH page 8 of 10


SysMem_V3x_E.doc
Library SysMem.library

2.13 SysMemSet
By use of this function a memory space is initialized with a specified value.

The return is an error code indicating success or failure of the operation (see document
"Runtime Error Codes").
Input variable Data type Description

pDest POINTER TO BYTE Pointer to memory address to be initialized


udiValue UDINT Character or value the memory is to be assigned to
udiCount UDINT Number of bytes to be initialized

2.14 SysMemSwap
This function serves to swap data within memory areas. It is mainly used to convert data from
Intel byte order to Motorola byte order. Thereby portable libraries can be built.

Note: Swapping will only be executed on Motorola target systems (PPC), but not on Intel
target systems (ARM, MIPS, SH, x86). Otherwise see SysMemForceSwap (2.6).

The return of type DINT equals

-1, if udiSize was assigned to an invalid value.

0, if swapping is not necessary (i.e. the data already has Intel byte order).

a value >0 reflecting the number of bytes swapped. In particular: return 1, if buffer is
of type Motorola and function has been called with pbyBuffer =NULL
Input variable Data type Description

pbyBuffer POINTER TO BYTE Pointer to address of memory area to be swapped


udiSize UDINT Number of positions forming a unit to be swapped;
valid: 2,4,8
udiCount UDINT Number of bytes to be swapped
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH page 9 of 10


SysMem_V3x_E.doc
Library SysMem.library

Change History
Version Description Date

0.1 Creation according to German version 1.0 20.02.2008


1.0 Release after formal review 20.02.2008
libdoc_e.dot / V1.0

3S - Smart Software Solutions GmbH page 10 of 10


SysMem_V3x_E.doc