pSOS to Linux OS Changer Reference Manual and Users’ Guide...This product comes in the form of a library providing support for pSOS™ kernel APIs integrated and optimized for Linux

pSOS to Linux OS Changer Reference Manual and Users’ Guide

pSOS® to Linux®

OSChanger®

Reference Manual and Users’ Guide

Copyright (c) 200

MapuSoft Technologi1301 Azalea RoaMobile, AL 3669

4esd3



Style and Symbol Conventions Program listings, program examples, filenames, menu items/buttons and interactive displays are each shown in a special font. Program listings and program examples - Courier New Filenames - COURIER NEW, ALL CAPS Interactive Command Lines - Courier New, Bold Menu Items/Buttons – Times New Roman Italic

Trademarks MapuSoftTM and OS Changer® are registered trademarks of MapuSoft Technologies L.L.C. All other company or product names are registered trademarks or trademarks of their respective owners.

Additional Assistance For additional assistance, please contact us at the following:

MapuSoft Technologies 1301 Azalea Road Mobile, Alabama 36693 251.665.0280 251.660.0288 FAX [email protected] http://www.mapusoft.com

Copyright (©) 2004, All Rights Reserved. The information detailed in this manual is subject to change. Last Revised: 7/1/2004

mailto:[email protected]

http://www.atinucleusmapusoft.com/


pSOS™ to Linux OS Changer Reference Manual and Users’ Guide

Style and Symbol Conventions.......................................................................iii

Trademarks .....................................................................................................iii

Additional Assistance .....................................................................................iii

Chapter 1 - Introduction................................................................................... 2

About OS Changer........................................................................................... 3

OS Changer and Linux OS Integration............................................................ 3

Chapter 2 – Getting Started.............................................................................. 4

How to Use OS Changer.................................................................................. 5

OS Changer Library Initialization ................................................................... 6

Device Drivers Initialization............................................................................ 7

Linux Time and Clock Initialization................................................................ 7

Memory Usage................................................................................................. 8

Priority Mapping from pSOS to Linux ............................................................ 8

Conditional Compilations ................................................................................ 9

Chapter 3 - Porting Guide .............................................................................. 11

Porting applications from pSOS® legacy code to Linux............................... 12

OS Changer Overview ................................................................................... 15

API Variations ............................................................................................... 16

Error Handling ............................................................................................... 21

API Reference................................................................................................ 23

Contents

v


Initialization ................................................................................................... 23 PS_Initialize....................................................................................................................... 23 SetUpDriver() .................................................................................................................... 24 InstallDrivers ..................................................................................................................... 25

Release Information ....................................................................................... 26 OSC_Release_Information ................................................................................................ 26

Error Handling ............................................................................................... 27 OSC_Fatal_Error ............................................................................................................... 27

Task Control................................................................................................... 28 t_create............................................................................................................................... 28 t_start ................................................................................................................................. 30 t_mode ............................................................................................................................... 31 t_restart .............................................................................................................................. 32 t_ident ................................................................................................................................ 33 t_suspend ........................................................................................................................... 34 t_delete............................................................................................................................... 35 t_resume............................................................................................................................. 36 t_setpri ............................................................................................................................... 37 t_setreg............................................................................................................................... 38 t_getreg .............................................................................................................................. 39

Region Memory ............................................................................................. 40 rn_create ............................................................................................................................ 40 rn_delete ............................................................................................................................ 41 rn_getseg............................................................................................................................ 42 rn_ident.............................................................................................................................. 43 rn_retseg ............................................................................................................................ 44

Partition Memory ........................................................................................... 45 pt_create............................................................................................................................. 45 pt_delete............................................................................................................................. 46 pt_getbuf............................................................................................................................ 47 pt_ident .............................................................................................................................. 48 pt_retbuf............................................................................................................................. 49 pt_sgetbuf .......................................................................................................................... 50

Fixed Queues ................................................................................................. 51 q_create.............................................................................................................................. 51 q_delete.............................................................................................................................. 53 q_send................................................................................................................................ 54 q_urgent ............................................................................................................................. 55 q_receive............................................................................................................................ 56 q_broadcast ........................................................................................................................ 57 q_ident ............................................................................................................................... 58

Variable Queues............................................................................................. 59 q_vcreate............................................................................................................................ 59


q_vdelete............................................................................................................................ 61 q_vsend.............................................................................................................................. 62 q_vurgent ........................................................................................................................... 63 q_vreceive.......................................................................................................................... 64 q_vbroadcast ...................................................................................................................... 66 q_vident ............................................................................................................................. 67

Semaphores .................................................................................................... 68 sm_create ........................................................................................................................... 68 sm_delete ........................................................................................................................... 69 sm_p................................................................................................................................... 70 sm_v................................................................................................................................... 71 sm_ident............................................................................................................................. 72

Events............................................................................................................. 73 ev_asend ............................................................................................................................ 73 ev_receive.......................................................................................................................... 74 ev_send .............................................................................................................................. 75

Signals............................................................................................................ 76 as_return ............................................................................................................................ 76 as_catch ............................................................................................................................. 77 as_send............................................................................................................................... 78

Device I/O Interface....................................................................................... 79 de_init ................................................................................................................................ 79 de_open.............................................................................................................................. 80 de_read............................................................................................................................... 81 de_write ............................................................................................................................. 82 de_cntrl .............................................................................................................................. 83 de_close ............................................................................................................................. 84

Timers ............................................................................................................ 85 tm_wkafter......................................................................................................................... 85 tm_evafter .......................................................................................................................... 86 tm_evevery ........................................................................................................................ 87 tm_cancel........................................................................................................................... 88 tm_set................................................................................................................................. 89 tm_get ................................................................................................................................ 90 tm_wkwhen ....................................................................................................................... 91 tm_evwhen......................................................................................................................... 92


1


Chapter 1 - Introduction

Introduction1

About OSChanger

OSChanger and Linux OSIntegration


About OS Changer OS Changer makes it easy to transition applications developed using pSOS™ kernel APIs to the Linux operating system. This product comes in the form of a library providing support for pSOS™ kernel APIs integrated and optimized for Linux operating system.

Porting is done in the following three steps: Remove references to the pSOS™ header files and the pSOS™ configuration tables within your application.

Set pre-processor defines to indicate OS selection and also the OS Changer APIs that you require to use

Include the Linux and OS Changer libraries and insert oschanger.h in your application.

Compile, link and download your application to the target. Resolve compiler or linker or run-time errors as appropriate

The pSOS™ APIs have gone through very little change over the past years and as a result this product should work with all pSOS™ versions. We also support older versions of pSOS APIs, so please contact MapuSoft for further help.

OS Changer and Linux OS Integration The library mostly uses POSIX API functions and may accesses Linux OS’s internal data structures to provide you further optimization under selected Linux Distribution. OS Changer may also be integrated with selected Linux vendors tools & IDE to provide you a out-of-the box solution. Some of the pSOS kernel APIs may be using more than one or more Linux equivalent APIs in order to provide the required pSOS API support. The OS Changer should work with all the versions of Linux that support POSIX 1003.1a, 1003.1b & 1003.1c API compliance in the field because there were no specific changes are required or made to the underlying Linux product.


3


Chapter 2 – Getting Started

Getting Started 2 How to Use OSChanger

OSChanger LibraryInitialization

Linux Timer and ClockInitialization

Memory Usage

Conditional Compilations

4


How to Use OS Changer OS Changer is designed for use as a C library. Services used inside your application software are extracted from the OS Changer and Linux libraries, and, are then combined with the other application objects to produce the complete image. This image may be downloaded to the target system or placed in ROM on the target system. Please refer to appropriate documentation for help with compiling, debugging and downloading your application to target.

The steps for using OS Changer are described in the following generic form:

• Remove the pSOS™ header file include defines from all your source files.

• Remove definitions and references to all the pSOS™ configuration data structures in your application.

• Include the OS Changer header file oschanger.h in all of the source files.

• In your project make file, define the RTOS for Linux, if you are using advanced real-time options of Linux, the appropriate compiler tool environment if required and other pre-processor options to build the OS Changer libraries and your application.

• Under Linux, the OSC_Application_Start function will be your main() routine. This function calls ps_Initialize which creates the pSOS root task. If some things need to be done for your application prior to root task creation, then place those code between OSC_RTOS_Init and ps_Initialize functions.

• Modify the Linux BSPs to match with your development board configurations (see appropriate Linux documentation).

• Customize the priority mapping if necessary within OSC_RTOS_Init function. OS Changer does an automatic mapping of the required 257 priorities to Linux somewhere in the middle of Native Linux’s lowest and highest priorities.

• Resolve the compiler and linker errors.

• Download the complete application image to the target system and resolve all the OS Changer generated run-time errors.

Please review the processor and development system documentation for additional information, including specific details on how to use the compiler, assembler, and linker. Please refer to the underlying Linux documentation to make the necessary changes to the BSP. It is recommended that you first bring up the standard OS demo application provided by the Linux product for your target first, prior to trying out porting applications via OS Changer. OS Changer is designed to be independent of the underlying hardware and operating system itself. It does not contain any assembly code. If you need any specific features of pSOS functions that is required but not provided by the standar OS Changer release, please contact MapuSoft Technologies. In most cases, we will be able to provide an easy work-around or may have an updated release covering those required functionalities.


OS Changer Library Initialization After, Linux initializes itself, your applications main() entry point is mapped directly to OS Changer’s OSC_Application_Start function where you will initialize your application if required. This function also provides a memory pointer for application’s run time memory needs. But under Linux OS, since all the & OS Changer’s and applications memory requirement are directly derived from the system heap, so you can safely ignore this parameter. There are four steps needed to be performed within the OSC_Application_Start() function located in PS_LX_INIT.C file module prior to using any of the OS Changer libraries:

1. Intialize OS Changer RTOS specific library by calling the OSC_RTOS_Init()

2. Insert any application specific code if necessary, before the root task get’s spawned

3. Initialize the OS Changer pSOS library by calling ps_Initialize().

4. Just Idle or sleep so that your linux program will not exit.

#include “oschanger.h” /* remove psos header file includes and use oschanger.h */ void Function_Root(UNSIGNED); /* root task – prototype definition */ ulong tRoot; /* Define the Root Task ID, this is initialized in ps_initialize func */

void OSC_Application_Start(VOID *first_available_memory) { OSC_RTOS_Init(); /* insert your code here !!!! */ /* OS Changer psos library initialzation and root task creation */ ps_Initialize(STACK_SIZE, &tRoot, Function_Root); for(;;) OSC_Sleep_Task(10000); /* just Idle here, after starting root,

Otherwise your program will EXIT !!! */ }

When there is a fatal system error and the pre-processor flag OSC_DEBUG is set, the execution will stop inside the OSC_Fatal_Error function define in osc_lx\osc_lx_usr.c file. To handle the error differently, insert your code within OSC_Fatal_Error.


Device Drivers Initialization The device drivers and the interrupt service routines needed to be ported to work under Linux. OS Changer provides the necessary application level API interface via the functions like de_init, de_open, and others. For each device that you access via the de_xxx interface, you will need to provide corresponding wrapper device driver routines for that device. The functions SetUpDrivers (see ps_usr.c module) will setup & install your driver. Setup installs the driver by calling InstallDriver along with providing required wrapper function pointers of the device specific routines. Within the wrapper rountines, use the device i/o routines to connect to the device and upon return, you can provide the driver response in the form how the application expects. This will greatly minimize changes to the application interacting with the Linux devices. When adding a driver, there are three steps:

Modify ps_oschanger.h to add the unique device ID with device major & minor values set accordingly. Note that the device major ID cannot exceed the define SC_DEVMAX value. If you need more drivers, then modify the SC_DEVMAX value accordingly. Code sample given below (refer to ps_oschanger.h also) adds device DEV_SERIAL_DEMO_DRV with the major number defined as SC_DEV_SERIAL_DEMO_DRV (equals to value 14, which is less than SC_DEVMAX) to the I/O system.

/* Device major ID value defined below */ #define SC_DEV_SERIAL_DEMO_DRV 14 /* major number */ /* Device unique ID (major ID value = 14; minor ID value = 0). Note that the major value is the most significant 16bits and minor value is the least significant 16bits */ #define DEV_SERIAL_DEMO_DRV (SC_DEV_SERIAL_DEMO_DRV << 16) Modify the SetUpDriver to install and setup the device driver. See code sample below: /* Install the DEMO SERIAL DRIVER */ /* Make sure you’re the major value of the device ID does not exceed the dev max value */ #if(SC_DEV_SERIAL_DEMO_DRV > SC_DEVMAX) #error "SC_DEV_SERIAL_DEMO_DRV cannot be > SC_DEVMAX" #endif /* sample installation and setup for the serial driver */ InstallDriver(SC_DEV_SERIAL_DEMO_DRV, DevSerialInit, DevSerialOpen, DevSerialClose, DevSerialRead, DevSerialWrite, DevSerialCntrl, 0, 0);

Develop your device specific routines. See dvserial.c module in the demo directory for sample device specific routines. Every device specific routine should return two values (errcode and retval) to the de_xxxx api interface as shown below prior to their function return: /* set driver return value */ iopb->out_retval = 0; iopb->err = EOK; NOTE: Please note that the return values are returned differently unlike how it pSOS does it. In pSOS, the return values are normally set in specific registers instead of how it is done above for OS Changer. However, this is much more convenient way since we are not reading writing to registers via assembly code.

Linux Time and Clock Initialization

In this release, tm_set and tm_get calendar time API calls are currently not supported.


The number of clock ticks is defined by OSC_TIME_TICK_PER_SEC, which is retrieved from the Linux system. Under Red Hat®/GNU® Linux, this is actually 100 (this means every tick equals to 10ms). However, the OSC_TIME_TICK_PER_SEC could be different under other real-time or proprietary Linux.

Setting the task Time-Slice value when creating pSOS tasks with the time slice option set will use the value called OSC_DEFAULT_TSLICE which is defined in OSC_LX.H. By default, this value is set for the time slice to be 100ms. Make sure you modify this value to match with your application needs if necessary.

Memory Usage OS Changer libraries used the system heap directly to provide the dynamic & partition pool memory. The Memory management and garbage collection is best left for the Linux kernel to be handled, so OS Changer does not restrict application with memory request from partition and/or dynamic memory pools. The maximum memory the application can use will depend on the memory availability of the system heap.

Priority Mapping from pSOS to Linux OS Changer first maps the pSOS priorities “0 to 255” to “255 to 0” OS Changer’s internal abstraction priority values. The abstraction priorities 256 plus one more for exclusivity are mapped to Linux utilizing a simple scheme (please refer to OSC_RTOS_INIT function defined in osc_lx.c ). OS Changer queries to kernel to find out the min and max priorities to first calculate the linux priority window. Then it maps the abstraction priorities one on one to Linux priorities by picking up a range exactly in the middle of the linux priority window. Please modify the priority scheme as necessary for your application. If you want to minimize the interruption of the external native linux applications then you would want the OS Changer abstraction priorities to map to the higher end of the linux priority window. OS Changer abstraction priority value of 257 is reserved internally by OS Changer to provide the necessary exclusivity among the OS Changer tasks when they request no preemption or task protection. The exclusivity and protections are not guaranteed if the external native Linux application runs at a higher priority. It is recommended that the Linux kernel be configured to have a priority of 512, so that the OS Changer priorities will use the window range in the middle and as such would not interfere with some of core Linux components. If your Linux kernel is configured to have less than 257 priorities, the OS Changer will automatically configuring a windowing scheme, where multiple number of OSC Changer priorities will map to a single Linux priority. Because of this, the reported priority value could be slightly different than what was used during the task creating process. If your application uses the pre-processor called OSC_DEBUG, then all the priority values and calculations will be printed when you call the OSC_RTOS_Init function.


Conditional Compilations Select the RTOS by setting the following compiler definition as follows:

Compilation Flag Meaning RTOS The value of this flag indicates the RTOS selection defined

in osc_changer.h: OSC_NUCLEUS – Nucleus PLUS from ATI OSC_THREADX – ThreadX® from Express Logic OSC_VXWORKS – VxWorks® from Wind River Systems OSC_MQX – Precise/MQX® from ARC® International OSC_ITRON – ITRON based operating system OSC_LINUX - Linux® OS If you are doing your own porting either to another commercial or proprietary RTOS, you could add your own define and include appropriate interface files. For Linux, define as RTOS = OSC_LINUX

Compilation Flag Meaning LINUX_ADV_REALTIME The value is to be used only when RTOS selection is

OSC_LINUX. If your Linux distribution supports LINUX_ADV_REALTIME then you would want to set this define to 1 as shown below: LINUX_ADV_REALTIME = 1 This would provide a better performance and timer resolution and also will take advantage of the advanced real-time extensions offered under some Linux distributions

Based on the compiler tools that you use, please select any one of the following definitions below (if your choice is not listed, you can ignore this pre-processor flag):

Compilation Flag Meaning ARM_TOOLS Using ADS tools from ARM® Ltd

GNU_TOOLS Using GNU Tools

MQX_TOOLS Using Metaware® Tools from ARC® International


Select the OS Changer components for your application use as follows:

Compilation Flag Meaning INCLUDE_OSC_ANSI This flag is NOT supported under LINUX OS

INCLUDE_OSC_IO Define this flag if your application needs the OS Changer

I/O API support

INCLUDE_OSC_PSOS Define this flag if your application needs to use the pSOS compatibility APIs (optional product)

INCLUDE_OSC_VXWORKS Define this flag if your application needs to use the VxWorks compatibility APIs (optional product)

INCLUDE_OSC_POSIX Define this flag if your application needs to use the POSIX compatibility APIs (optional product)

Select the if running under windows emulation & prototyping environment:

Compilation Flag Meaning BUILDING_ON_WIN32 This option is NOT supported under RTOS = LINUX at the

moment mainly because Cygwin does not support all the required posix APIs that OS Changer needs. If you are building on Windows computer using RTOS prototyping environment (NOT instruction set simulator) then define this flag. Also you should not define this flag if you are building the application for a specific target.

Select the following definition if you want to OS Changer to enable error checking for debugging purposes:

Compilation Flag Meaning OSC_DEBUG_INFO Enable error checking for debugging


Chapter 3 - Porting Guide

Porting Guide

3 Porting applications from pSOS®

legacy code to Linux

OS Changer Overview

API Variations

Error Handling

Release Information

API Reference

11


Porting applications from pSOS® legacy code to Linux In most applications, using OS Changer is straightforward. The effort required in porting is mostly at the underlying driver layer. Since we do not have specific information about your application, it will be hard to tell how much work is required. However, we want you to be fully aware of the surrounding issues upfront so that necessary steps could be taken for a successful and timely porting. This section provides porting guidelines in two different flow charts. The first one (chart A) covers issues relating with OS Changer, device drivers, interrupt service routines, etc. The second flowchart (chart B) covers issues relating to other add-on components (like pHILE) that application may use. It is possible that we have not addressed all your application specific issues in the flow chart, so please contact MapuSoft Technologies for further information.


Porting pSOSTM Applications to LINUX - GuidelinesChart A - Kernel APIs, interrupts and device drivers

Yes

START

No

YesCHECK 1

Does your application uses any pSOS kernelAPIs' that are not supported by

OSCHANGER?

Go To Chart B

Implement theunsupported APIs

using LINUX

No

Yes

CHECK 2Does your application uses any pSOS APIs'

provided by OSCHANGER that are littledifferent from the original APIs?

Modify yourapplication to

handle thedifferences

No

Yes

CHECK 4Does your application configure the target

hardware differently than what was validatedby the new RTOS you have chosen?

Modify the port specificcode or BSP to make itwork for your board. It is

highly recommendedtoget a native demo

application running onyour target prior to

porting

No

YesCHECK 5

Are you using pSOS based device drivers?

Use device wrapper functionsto interact with the driver to

minimize changes toapplication. Port the pSOS

device driver to Linux

CHECK 3Does your application require call-out routines

functions provided by pSOS kernel?

Modify OSCHANGERand/or implement themusing Linux alternatives

No

No

YesCHECK 6

Are you using interrupt service routines thatare unaware to or unmanaged by pSOS?

Port them to work underLinux


START

No

YesCHECK 1

Does your application uses pNA+ networkingcomponent provided by pSOS?

HAPPY PORTING

Port API interfacesand drivers toLinux via usingBSD socket

interface APIs. Ifyou prefer to use athird party stack forany reason, thenmake sure it willwork under Linux

No

YesCHECK 2

Does your application uses pHILE filemanagement APIs provided by pSOS?

Port API interfacesand drivers to

Linux

No

YesCHECK 3

Does your application uses OpTIC graphicsAPIs provided by pSOS?

Port API interfacesand drivers to

native or third partygraphics product

No

YesCHECK 4

Does your application uses pREPC+ libraryAPIs provided by pSOS?

Utilize the CLIB provided by Linux. Checkto make sure the CLIB APIs you use are

re-entrant for your multi-taskingenvironment

Porting pSOSTM Applications to Linux - GuidelinesChart B - Other Components


OS Changer Overview The OS Changer contains the following modules, which can be found at the installation directory:

Module Description OSCHANGER.H This header files include RTOS specific components and

also components that is required for the application

PS_OSCHANGER\PS_OSCHANGER.H This header file provides the translation layer between the pSOS™ defines, APIs and parameters to OS Changer’s virtual abstraction definition, which then re-maps to Linux equivalents

PS_OSCHANGER\PS_I.C Provides the pSOS OS Changer initialize function PS_OSCHANGER\PS_AS.C Provides pSOS™ signal handling APIs PS_OSCHANGER\PS_EV.C Provides pSOS™ event handling APIs PS_OSCHANGER\PS_T.C Provides pSOS™ task handling APIs PS_OSCHANGER\PS_PT.C Provides pSOS™ partition memory management APIs PS_OSCHANGER\PS_RN.C Provides pSOS™ memory region management APIs PS_OSCHANGER\PS_Q.C Provides pSOS™ fixed and variable queue APIs PS_OSCHANGER\PS_SM.C Provides pSOS™ semaphore handling APIs PS_OSCHANGER\PS_TM.C Provides pSOS™ timer, time and date APIs PS_OSCHANGER\PS_DE.C Provides pSOS™ of device and driver APIs OSC_LX\OSC_LL.C Provides link list manipulation OSC_LX\OSC_LX.H OSC to Linux compile time mapping module OSC_LX\OSC_LX.C OSC to Linux function mapping module OSC_LX\OSC_LX_INIT.C OS initialization to start application - function main()

User configurable module. OSC_NU\OSC_LX_USR.C Configure fatal error handler rountines to your needs DEMO\PS_OSCHANGER\PS_LX_INIT.C User configurable Linux initialization module

User condigurable module. DEMO\PS_OSCHANGER\PS_DEMO.C Sample pSOS demo application that runs on Linux DEMO\PS_OSCHANGER\PS_DVSERIAL.C Sample pSOS device driver code DEMO\PS_OSCHANGER\PS_USR.C User configurable module to setup pSOS drivers init

configurations. NOTE: Please install OS Changer in the root file system (Rfs) under the folder called ‘opt’, in a directory called ‘mapusoft’. Please be aware that the Rfs path location would be different depending on if you are working or doing a a cross-compiling.


API Variations Since support is being added in each releases, please contact MapuSoft to get latest support information. OS Changer 3.0 support’s approx 90% of pSOS™ kernel APIs. Minor differences are noted in the ‘Notes’ column.

pSOS™ API Support Notes ev_receive YES ev_send YES pt_create YES • Request to provide memory from a physical

address will be ignored and instead, the memory will be from logical address space

• OS Changer will depend on the Linux to provide memory management, garbage collection, de-fragmentation, etc since it uses the standard malloc calls for memory allocations. Given this situation, there is a possibility that a memory request at run-time could be denied

• No multi-processor support, all partitions created in local node only

• PT_NODEL – Prevents deletion of partitions with outstanding buffers – not supported

pt_delete YES • Allows deletion of the partition even when

there are pending memory allocation requests

pt_getbuf YES pt_ident YES • Planned to be added in next release

pt_retbuf YES pt_sgetbuf YES • The value returned for laddr for logical

address and paddr for physical address will be the same and memory will always be from logical address space

q_broadcast NO q_create YES • Zero (0) length queues are not supported –

variable count parameter cannot be zero (0) • Q_FIFO unsupported, instead Q_PRIOR used


q_delete YES • Allows deletion of the queue in the situations where the tasks are still waiting on the queue OR undelivered messages are still in the queue

q_ident YES • Planned to be added in next release

q_receive YES q_send YES q_urgent NO q_vbroadcast NO q_vcreate YES • Q_FIFO unsupported, instead Q_PRIOR used

q_vdelete YES • Allows deletion of the queue in situations

where the tasks are waiting on the queue OR undelivered messages are still in the queue

q_vident YES • Planned to be added in next release

q_vreceive YES • The parameter buf_len will be ignored. The message will be copied to msg_buf based on its actual size of the message

q_vsend YES q_vurgent YES rn_create YES • Option PT_NODEL to prevent the deletion of

the partition with outstanding buffers is not supported

• RN_FIFO unsupported, instead RN_PRIOR used

rn_delete YES • Allows deletion of the region even when there

are pending memory allocation requests.

rn_getseg YES rn_ident YES • Planned to be added in next release

rn_retseg YES sm_create YES • Global semaphores will be created in the local

node • SM_FIFO ignored, instead SM_PRIOR used

sm_delete YES sm_ident YES • Planned to be added in next release

sm_p YES


sm_v YES t_create YES • The value for the node variable has to be zero

• User stack size parameter will be ignored. The task stack size will be default size configured by the Linux kernel

• All tasks requested to run in supervisor mode will only run in user mode

• The flag option T_FPU indicating the task to use the floating point coprocessor is not supported

t_delete YES t_getreg YES t_ident YES • Planned to be added in next release

t_mode YES • T_ISR flag to disable all interrupts while the

task is running is not supported

t_start YES • T_ISR flag to disable all interrupts while task is running is not supported

• All tasks requested to run in user mode will only run in supervisor mode

t_restart YES t_setreg YES • Planned to be added in next release

t_setpri YES t_suspend YES t_resume YES tm_cancel YES tm_evafter YES • Implicit calls to tm_cancel have to be issued

to stop and remove the timers from the system. There is no automated cancel of the timers when the task is restarted

tm_evevery YES • Implicit calls to tm_cancel have to be issued

to stop and remove the timers from the system when the tasks are restarted or deleted.

tm_evewhen NO tm_get YES • Planned to be added in next release

tm_set YES • Planned to be added in next release


tm_tick NO • This function is not required under LINUX

tm_wkafter YES tm_wkwhen NO de_close YES • Device specific routines needs to return value

as return code instead of setting them up in the registers. The underlying device driver routines need to be ported to work under Linux in order for these routines to work

de_open YES • Device specific routines needs to return value


de_cntl YES • Device specific routines needs to return value


de_read YES • Device specific routines needs to return value


• This call does NOT block the calling task for interrupt based devices, which is unlike how it is in pSOS. The driver routine needs to relinquish task control until the ISR completes the task and then it will resume the calling task

de_write YES • Device specific routines needs to return value


de_init YES • Device specific routines needs to return value


k_fatal YES • Use OSC_Fatal_Error instead


as_catch NO as_send NO as_return NO ev_asend YES • Behavior will be similar to ev_send() API


Error Handling

Applications will receive a run-time error of -1 (ERR_NOT_SUPPORTED defined in PS_OSCHANGER.H) on some occasions. This happens due to either:

Unsupported pSOS™ API function call, or

Unsupported parameter value or flag option in a pSOS™ API call, or

Error occurred for which there is no matching pSOS™ error code.

OS Changer calls OSC_FatalError and passes along an error code and error string. The non-zero value in the error code means a corresponding Linux API call failed. Refer to the table below for a list of errors and the reasons for their occurrence.

The error handler OSC_Fatal_Error() is coded to stop execution upon occurrence of an error. If you have built the OS Changer library using the BUILDING_ON_MNT compiler command line define, then the following error string will be displayed on the screen.

OS Changer API Error String Reason for Failure q_create Q_NOLIMIT option is not

supported Unlimited queue is not supported.

q_create Zero (0) length queues are not supported

The variable count should not be zero (0).

t_create FPU not supported The underlying Linux may already support FPU operations

tm_wkwhen tm_evwhen tm_tick t_ident sm_ident rn_ident pt_ident q_broadcast q_ident q_vident as_send as_catch as_return

Not supported


The following table maps OSC Errors with Linux errors. Refer to OSC_lx.h module for more information. OS Changer Error Actual Value OSC_SUCCESS 0 ERR_NOT_SUPPORTED -1 OSC_ERR_DELETED -2 OSC_ERR_DELETE -3 OSC_ERR_ENABLE -5 OSC_ERR_ENTRY -6 OSC_ERR_FUNCTION -7 OSC_ERR_GROUP -8 OSC_ERR_MEMORY -11 OSC_ERR_MESSAGE -12 OSC_ERR_OPTION -13 OSC_ERR_PIPE -14 OSC_ERR_PTR -15 OSC_ERR_POOL -16 OSC_ERR_PREEMPT -17 OSC_ERR_PRIORITY -18 OSC_ERR_QUEUE -19 OSC_ERR_RESUME -20 OSC_ERR_SEMAPHORE -21 OSC_ERR_SIZE -22 OSC_ERR_START -23 OSC_ERR_SUSPEND -24 OSC_ERR_TASK -25 OSC_ERR_TIMER -26 OSC_ERR_NO_MEMORY -32 OSC_ERR_NO_PARTITION -34 OSC_ERR_NOT_DISABLED -35 OSC_ERR_NO_EVENT -36 OSC_ERR_NOT_REGISTERED -37 OSC_ERR_NOT_TERMINATED -38 OSC_ERR_PIPE_DELETED -39 OSC_ERR_PIPE_EMPTY -40 OSC_ERR_PIPE_FULL -41 OSC_ERR_PIPE_RESET -42 OSC_ERR_POOL_DELETED -43 OSC_ERR_QUEUE_DELETED -44 OSC_ERR_QUEUE_EMPTY -45 OSC_ERR_QUEUE_FULL -46 OSC_ERR_QUEUE_RESET -47 OSC_ERR_SEMAPHORE_DELETED -48 OSC_ERR_SEMAPHORE_RESET -49 OSC_ERR_TIMEOUT -50 OSC_ERR_NO_SEMAPHORE -51


API Reference

Initialization

PS_Initialize Define the OSC_Application_Start that determines the initial Linux application environment.

Starts the root task. This function also calls SetUpDrivers() to install and setup required devices drivers. STACK_SIZE,&tRoot,Function_Root Parameters

Parameter Meaning ULONG MemorySize Memory size for the root task in bytes. ULONG *tid TCB ID of the root task. VOID (* entrypt) Entry point of the root task.

Special Notes This routine must be called in the OSC_Application_Start function prior to using any pSOS™ API calls.


SetUpDriver() This function will be developed by the application user to install & setup drivers required by the application via a call to InstallDriver and then calls driver setup function if needed. Modify this function to suit your application needs. This function is called by the PS_Initialize function. This function cannot be called within a task or ISR and can only be invoked within PS_Initialize() in the function App_Initialize(). ALSO, SC_DEVMAX (max number of device drivers) */ should have been defined with proper value in ps_oschanger.h

Parameters Parameter Meaning None

Return Value Return Value Meaning None

Special Notes


InstallDrivers Install driver handlers in pSOS IO table.

Parameters Parameter Meaning unsigned short major_number device major number void (*dev_init)() device init procedure void (*dev_open)() device open procedure void (*dev_close)() device close procedure void (*dev_read)() device read procedure void (*dev_write)() device write procedure void (*dev_ioctl)() device control procedure unsigned long rsvd1 Not used unsigned long rsvd2 Not used

Return Value Return Value Meaning OSC_NULL Failed to set up drivers. Valid Memory pointer A pointer that was incremented depending

on memory usage from AvailMemPtr

Special Notes


Release Information

OSC_Release_Information Provides a string containing the OS Changer and the underlying RTOS release information.

Parameters

Parameter Meaning None

Returns This routine returns a character pointer to a string that contains OS Changer and RTOS release information.

Special Notes


Error Handling

OSC_Fatal_Error OS Changer provides the user an error handler template function, which can be modified to your specific needs. OS Changer calls this function when an error occurs within the library module. Use this function instead of k_fatal(). See the section “Error Handling” in Chapter 3 of this document for more details.

Parameters Parameter Meaning CHAR * fmt Contains the description text of the error. ULONG arg1 If not zero (0), it will be the return code

from a Linux kernel API call. ULONG arg2 Not used. ULONG arg3 Not used. ULONG arg4 Not used. ULONG arg5 Not used. ULONG arg6 Not used.

Return Value None

Linux Functions Called None

Special Notes The OS Changer library calls the OSC_Fatal_Error function when it detects an unsupported request or a problem that cannot be resolved. Users can modify the function and add code to handle various errors encountered (see section “Error Handling” Chapter 3).


Task Control

t_create Creates a task.

Parameters Parameter Meaning CHAR name[4] Four (4) byte name tag for the task. ULONG priority Valid ranges are 1 - 255. Priority 1 is low,

255 is highest. ULONG superstk Supervisor stack size. This value is ignored

under Linux, instead kernel default used. ULONG userstk User stack size. This value is ignored

under Linux, instead kernel default used. ULONG flags Option flags:

T_FPU – Enables task to use the Floating Point Unit coprocessor. Option is not supported. But underlying Linux may already support math co-processorT_NOFPU – Task does not use the FPU coprocessor. Underlying Linux may already support floating point calculations T_GLOBAL – Makes task global across multiprocessor. The task is automatically created to run in a single processor.T_LOCAL – Create the task to run in local mode or single processor mode.

ULONG *tid TCB ID – Return Task ID number.

Return Value Return Value Meaning EOK Successful. ERR_TINYSTK Invalid stack size. ERR_PRIOR Priority is out of range. ERR_NOSTK No memory to allocate requested stack

space.

Linux Functions Called OSC_Allocate_Memory -> TBD


Special Notes No multiprocessor support, therefore the value for the node variable has to be zero (0).

User stack size & supervisor stack parameter value are ignored. The task stack size is derived from the default Linux kernel configuration.

All tasks requested to run in supervisor mode run will run in supervisor mode.

The flag option, T_FPU, indicates the floating point coprocessor is not supported.

Actual Linux thread creation occurs only during execution of the corresponding t_start API call.


t_start Starts a task.

Parameters Parameter Meaning ULONG tid TCB ID required. ULONG mode, Initial task mode:

T_PREEMPT – Task can be preempted.T_NOPREEMPT – Task cannot be preempted. T_NOTSLICE – Task cannot be time sliced.T_TSLICE – Task can be time sliced.T_ASR – Enable tasks ASR.T_NOASR – Disable tasks ASR.T_USER – Task runs in user mode. This option is not supported. The task will always run in the supervisor mode.T_SUPV – Task runs in supervisor mode.T_ISR – Disable all interrupts when task is running.

void (*entrypt) Entry point for the task. ULONG targs[] Arguments for the task.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid Task ID.

Linux Functions Called OSC_Create_Task -> TBD OSC_Create_Event_Group -> TBD OSC_Resume_Task -> TBD

Special Notes T_ISR flag to disable all interrupts while the task is running is not supported.

All tasks requested to run in user mode run in supervisor mode.


t_mode Gets or changes the calling task’s execution mode.

Parameters Parameter Meaning ULONG mask Specifies which mode bits to change.

T_PREEMPT – Task can be preempted.T_NOPREEMPT – Task cannot be preempted. T_NOTSLICE – Task cannot be time sliced.T_TSLICE – Task can be time sliced.T_ASR – Enable tasks ASR.T_NOASR – Disable tasks ASR.T_ISR – Disable all interrupts when task is running. T_NOISR – Do not mask interrupts. NOTE: To specify a particular attribute for modification, the symbolic constants for that attribute must be OR-ed together in the mask parameter. For example, if you want to change the preemption and time slice attributes, the mask value will be equal to T_PREEMPT | T_NOPREEMPT | T_TSLICE | T_NOTSLICE.

ULONG newmode New task mode to set . ULONG *oldmode Returns the value of the old task mode.


Linux Functions Called

OSC_Current_Task_Id -> TBD

Special Notes T_ISR flag to disable all interrupts while task is running is not supported.


t_restart Restarts the task.

Parameters Parameter Meaning ULONG tid TCB ID required. UNSIGNED targs[] Arguments for the task


Linux Functions Called INT_OSC_Restart_Task ->TBD

Special Notes


t_ident Gets the first task’s ID to correspond to a task name. This API is NOT SUPPORTED in this release.

Parameters Parameter Meaning CHAR t_name[4] Name of the task for which the ID is

required. If t_name is NULL then current task’s ID will be returned.

ULONG node Only value allowed is node = 0 for a local or single processor.

ULONG *tid The first task’s ID that matches with the t_name input is returned by this call.

Return Value Return Value Meaning EOK Successful. ERR_OBJNF Task not found. ERR_NODENO Node other than node=0 is NOT

supported.

Linux Functions Called OSC_Current_Task_Id -> Not Applicable INT_OSC_Task_Ident -> Not Applicable

Special Notes No multiprocessor support, therefore the value for the node variable has to be zero (0).


t_suspend Suspends the task permanently until the application resumes it explicitly via t_resume call.

Parameters Parameter Meaning ULONG tid TCB ID required. If you suspend the

current task (tid=0), suspension occurs immediately and the call will never return unless this task is resumed by another task.

Return Value Return Value Meaning EOK Successful. ERR_OBJNF Task not found.

Linux Functions Called OSC_Suspend_Task->

Special Notes


t_delete Deletes the task regardless of the task’s state.

Parameters Parameter Meaning ULONG tid TCB ID required.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Task invalid.

Linux Functions Called OSC_Current_Task_Id -> TBD OSC_Delete_Task -> TBD OSC_Delete_Event_Group -> TBD OSC_Deallocate_Memory -> TBD

Special Notes


t_resume Removes suspension set by t_suspend call.

Parameters Parameter Meaning ULONG tid TCB ID required.

Return Value Return Value Meaning EOK Successful. ERR_NOTSUSP Task was not suspended before. ERR_OBJNF Task not found.

Linux Functions Called OSC_Current_Task_Id -> TBD OSC_Resume_Task-> TBD


t_setpri Gets the current value and/or changes the task priority dynamically.

Parameters Parameter Meaning ULONG tid TCB ID required. tid = 0 means it is

the current task. ULONG newprio The priority value to be set. If newprio=0,

then the function just returns the value of the task priority without changing it.

ULONG *oldprio Task's old priority.

Return Value Returns the values of the old_priority.

Linux Functions Called OSC_Current_Task_Id -> TBD OSC_Change_Task_Priority -> TBD


t_setreg Updates application registers in TCB.

Parameters Parameter Meaning ULONG tid TCB ID required. tid = 0 means it is the

current task. ULONG regnum Number of register to set. ULONG regvalue Value to set register to.

Return Value Return Value Meaning EOK Successful.



t_getreg Retrieves application registers in TCB.

Parameters Parameter Meaning ULONG tid TCB ID required. tid = 0 means it is the

current task. ULONG regnum Number of register to set. ULONG *regvalue Value to set register to.




Region Memory

rn_create Creates a variable segment memory from the memory pool.

Parameters Parameter Meaning CHAR name[4] Four (4) byte memory region or pool

name. void * addr Starting memory address. ULONG length Length of region in bytes. ULONG unit_size Unit of region memory allocation in bytes.

OS Changer ignores this value, because Linux does not require this info.

ULONG flags RN_PRIOR – Queue tasks by priority. RN_FIFO – Queue tasks by FIFO order. RN_DEL – Allow deletion of memory region while tasks waiting to acquire memory. RN_NODEL – Does not allow region to be deleted if tasks are waiting to acquire memory from this region. This option is not supported.

ULONG *rnid Region ID returned by this call. ULONG *asiz Maximum memory that is available for

allocation. This value is returned by this call.

Return Value Return Value Meaning EOK Successful. ERR_NOMGB If unable to allocate message buffers.

Linux Functions Called OSC_Allocate_Memory -> TBD OSC_Create_Memory_Pool -> TBD

Special Notes Option PT_NODEL to prevent deletion of a memory region with outstanding buffers is not supported.


rn_delete Deletes a variable segment memory region/pool.

Parameters Parameter Meaning ULONG rnid Region ID.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid memory region / pool . ERR_SEGINUSE Unable to delete. One or more segments

are still in use. This option is not supported.

ERR_TATRNDEL Unable to delete. Pending memory allocation requests. This option is not supported.

Linux Functions Called OSC_Delete_Memory_Pool -> TBD

Special Notes Allows deletion of the region even while tasks are waiting on pending memory allocation requests.


rn_getseg Allocates a block of memory segment from the memory region / pool.

Parameters Parameter Meaning ULONG rnid Region ID. ULONG size Length of memory segment in bytes. ULONG flags Wait flag:

RN_NOWAIT – Does not wait for segment to be available. RN_WAIT – Wait until segment becomes available (task will be suspended until memory becomes available).

ULONG timeout Timeout in clock ticks. This is valid only with flag option RN_WAIT.

void ** segaddr Returned segment address.

Return Value Return Value Meaning EOK Successful. ERR_NOSEG Unable to allocate message buffers. ERR_OBJID Invalid pool or input parameters. ERR_RNKILLD While waiting for memory, the region was

deleted. ERR_TIMEOUT Time out waiting for memory.

Linux Functions Called OSC_Allocate_Memory -> TBD


rn_ident Gets the region identifier of the named region. This API is NOT SUPPORTED in this release.

Parameters Parameter Meaning CHAR name[4] Four (4) byte memory region or pool name

for which the region ID is required. ULONG *rnid Return the first memory region ID value

that matches with the name.

Return Value Return Value Meaning EOK Successful. ERR_OBJNF Not found.

Linux Functions Called INT_OSC_Dynamic_Pool_Ident -> TBD


rn_retseg Returns a block of memory segment to the region from which it was allocated.

Parameters Parameter Meaning ULONG rnid Region ID. void * segaddr Segment address.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid pool and/or segment address.

Linux Functions Called OSC_Deallocate_Memory -> TBD


Partition Memory

pt_create Creates a memory partition of fixed size buffers.

Parameters Parameter Meaning CHAR name[4] Four (4) byte memory region/pool name. void * paddr Starting physical memory address. This

parameter is ignored under Linux void * laddr Starting logical memory address.

This value is ignored because OS Changer does not support MMU option.

ULONG length Length of partition in bytes. ULONG bsize Buffer size. ULONG flags PT_GLOBAL – Partition addressable

globally across multiple processors. This option is not supported. PT_LOCAL – Addressable within local or single processor address space. PT_DEL – Allows deletion of this partition while tasks are still waiting with memory allocation request. PT_NODEL – Prevents deletion of this pool if there are pending memory requests. This option is not supported.

ULONG *ptid Partition ID. ULONG *nbuf Max number of buffers that is available for

the application.


Linux Functions Called OSC_Allocate_Memory -> TBD OSC_Create_Partition_Pool -> TBD

Special Notes No MMU support, therefore, the parameter laddr for logical address is ignored. No multiprocessor support, therefore, all partitions are created in local node only. PT_NODEL prevents deletion of a partition with outstanding buffers. This is not supported.


pt_delete Deletes a fixed block memory region/pool.

Parameters Parameter Meaning ULONG ptid Partition ID to delete.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid memory region / pool. ERR_BUFINUSE Unable to delete. One or more buffers still

in use. This option is not supported.

Linux Functions Called OSC_Delete_Partition_Pool -> TBD

Special Notes Allows deletion of the partition even while tasks are waiting on pending memory allocation requests.


pt_getbuf Gets a fixed size buffer from the memory partition.

Parameters Parameter Meaning ULONG ptid Partition ID. void ** bufaddr Returned buffer address.

Return Value Return Value Meaning EOK Successful. ERR_NOBUF Unable to allocate message buffers. ERR_OBJID Invalid pool or input parameters.

Linux Functions Called OSC_Allocate_Partition -> TBD


pt_ident Gets the partition ID of the named partition. This API is NOT SUPPORTED in this release.

Parameters Parameter Meaning CHAR name[4] Four (4) byte memory region or pool

name. ULONG node Multiprocessor option is not supported.

The node value should always be zero (0). ULONG *ptid Return the first memory region ID that

corresponds with the name.

Return Value Return Value Meaning EOK Successful. ERR_NODENO Invalid node. ERR_OBJNF Invalid pool or input parameters.

Linux Functions Called INT_OSC_Part_Ident -> TBD


pt_retbuf Returns a block of memory from the memory region / pool.

Parameters Parameter Meaning ULONG ptid Region ID. void * bufaddr buffer address.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid pool or buffer addr.

Linux Functions Called OSC_Deallocate_Partition -> TBD


pt_sgetbuf Gets a memory buffer from fixed block along with returning both a physical and logical address.

Parameters Parameter Meaning ULONG ptid Partition ID. void ** paddr Physical address. void ** laddr MMU not supported. The value will be

same as paddr.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid pool or buffer addr.

Linux Functions Called pt_getbuf -> TBD

Special Notes


Fixed Queues

q_create Creates a fixed length message queue. The element size is fixed and is 16 bytes long (refer to OSC_FIXEDQ_ELEMENT_SZ defined in PS_OSCHANGER.H if you prefer to modify this length).

Parameters Parameter Meaning CHAR name[4] Four (4) byte queue name. ULONG count Maximum number of queue elements. The

value for count = 0 indicates it is a zero (0) length queue; therefore, it is not supported.

ULONG flags Q_NOLIMIT option is not supported. Q_GLOBAL – Queue is addressable globally across multiple processors. This option is ignored. Q_LOCAL – Queue is addressable only in the local processor. Q_PRIOR – Tasks queued by task’s priority. Q_FIFO – Tasks queued by FIFO. Q_LIMIT – Limits the queue to the number of elements specified in the count parameter. Q_NOLIMIT – Unlimited queue size. This option is not supported. Q_PRIBUF – Allocate private buffers for message storage. This option will be treated the same as Q_SYSBUF. Q_SYSBUF – Use system buffers for message storage.

ULONG *qid Queue ID returned by this call.

Return Value Return Value Meaning EOK Successful. ERR_NOMGB Unable to allocate message buffers.


Linux Functions Called OSC_Allocate_Memory -> TBD OSC_Create_Queue -> TBD OSC_Deallocate_Memory -> TBD

Special Notes Q_NOLIMIT for unlimited messages in the queue is not supported. But linux does not restrict allocation until system heap runs out.

Zero (0) length queues are not supported because the variable count parameter cannot have a value of zero (0).


q_delete Deletes a fixed message queue.

Parameters Parameter Meaning ULONG qid Queue ID for deletion.

Return Value Return Value Meaning EOK Successful. ERR_TATQDEL Tasks are still waiting on the queue. This

option is not supported. ERR_TATQDEL There are still undelivered messages in the

queue. This option is not supported.

Linux Functions Called OSC_Delete_Queue -> TBD OSC_Deallocate_Memory -> TBD

Special Notes Allows deletion of the queue in the situation where either tasks are waiting on the queue or there are undelivered messages in the queue. All the undelivered messages will be lost.


q_send Sends a fixed length message to the message queue.

Parameters Parameter Meaning ULONG qid Queue ID. ULONG msg_buf[4] Pointer to 16 byte data.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid queue or memory pointer. ERR_OBJDEL Queue already deleted. ERR_QFULL Queue is full.

Linux Functions Called OSC_Send_To_Queue -> TBD


q_urgent This API is NOT supported. Sends a fixed length message to the message queue and places the message in front of the messages already in the queue.

Parameters Parameter Meaning ULONG qid Queue ID. ULONG msg_buf[4] Pointer to 16 byte data.


Linux Functions Called OSC_Send_To_Front_Of_Queue -> TBD


q_receive Receives a fixed length message from the message queue.

Parameters Parameter Meaning ULONG qid Queue ID for receiving messages. ULONG flags Options:

Q_NOWAIT – Do not wait for messages. Q_WAIT – Wait for messages.

ULONG timeout Ticks to wait. If the timeout value is zero (0) and the Q_WAIT flag is set, then the call waits until a message arrives.

ULONG msg_buf[4] Pointer to 16 data buffer where the received message is copied.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid queue or memory pointer. ERR_QFULL Queue is full. ERR_TIMEOUT Time out waiting for a message (when

Q_WAIT is set along with a timeout value). ERR_NOMSG No message in the queue (when flag

Q_NOWAIT is set). ERR_QKILLD Queue was deleted while waiting for a

message.

Linux Functions Called OSC_Receive_From_Queue -> TBD


q_broadcast This API is NOT supported. Sends a fixed length message to each task that is waiting on the queue.

Parameters Parameter Meaning ULONG qid Queue ID. ULONG msg_buf[4] Pointer to 16 byte message data to send. ULONG *count Return a value indicating the number of

tasks that receives this message. This is not supported. A value of (-1) is always returned.


Linux Functions Called INT_OSC_Broadcast_To_Queue -> TBD

Special Notes Does not provide the value for the count variable which indicates the number of tasks receiving this broadcast message.


q_ident Gets the queue ID of the named fixed message queue. This API is NOT SUPPORTED in this release.

Parameters Parameter Meaning CHAR q_name Queue name for which the queue ID uses. ULONG node The value for the node should always be

zero (0) to indicate single processor mode. ULONG *qid The first queue ID that matches with the

q_name is returned.

Return Value Return Value Meaning EOK Successful. ERR_OBJNF Queue name not found. ERR_NODENO This will be returned if node value is not

zero (0).

Linux Functions Called INT_OSC_Queue_Ident -> TBD

Special Notes No multiprocessor support, therefore the value for the node variable should always be zero (0).


Variable Queues

q_vcreate Creates a fixed length message queue of the user defined number of messages.

Parameters Parameter Meaning CHAR name[4] Four (4) character long queue name. ULONG flags Q_NOLIMIT option is not supported.

Q_GLOBAL – Queue is addressable globally across multiple processors. This option is ignored. Q_LOCAL – Queue is addressable only in the local processor. Q_PRIOR – Tasks queued by task’s priority. Q_FIFO – Tasks queued by FIFO. Q_LIMIT – Limits the queue to number of elements specified in count parameter. Q_NOLIMIT – Unlimited queue size. This option is not supported. Q_PRIBUF – Allocate private buffers for message storage. This option will be treated same as Q_SYSBUF. Q_SYSBUF – Use system buffers for message storage.

ULONG count Maximum number of queue elements. The value for count = 0 indicates it is a zero (0) length queue; therefore, it is not supported.

ULONG maxlength Maximum size of an individual message element (in bytes).

ULONG *qid Queue ID returned by this call.



Linux Functions Called OSC_Allocate_Memory -> TBD OSC_Create_Pipe -> TBD OSC_Deallocate_Memory -> TBD

Special Notes Q_NOLIMIT for unlimited messages in the queue is not supported, but under Linux there is no memory restriction


q_vdelete Deletes a variable message queue.

Parameters Parameter Meaning ULONG qid Queue ID for deletion.

Return Value Return Value Meaning EOK Successful. ERR_TATQDEL Tasks are still waiting on the queue. This

option is not supported. ERR_TATQDEL Still there are undelivered messages in the

queue. This option is not supported.

Linux Functions Called OSC_Delete_Pipe -> TBD OSC_Deallocate_Memory -> TBD

Special Notes Allows deletion of the queue in the situation where either tasks are waiting on the queue or there are undelivered messages in the queue. All the undelivered messages will be lost.


q_vsend Sends a variable length message to the queue.

Parameters Parameter Meaning ULONG qid Queue ID. void * msg_buf Pointer to data. ULONG msg_len Length of message.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid queue or memory pointer. ERR_OBJDEL Queue already deleted. ERR_QFULL Queue is full. ERR_MSGSIZE Invalid message size.

Linux Functions Called OSC_Send_To_Pipe -> TBD


q_vurgent Sends a variable length message to the message queue and places the message in front of other messages already in the queue.

Parameters Parameter Meaning ULONG qid Queue ID. void * msg_buf Pointer to data. ULONG msg_len Length of message.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid queue or memory pointer. ERR_OBJDEL Queue already deleted. ERR_QFULL Queue is full. ERR_MSGSIZE Invalid message size.

Linux Functions Called OSC_Send_To_Front_Of_Pipe -> TBD


q_vreceive Receives variable length message from the message queue.

Parameters Parameter Meaning ULONG qid Queue ID for receiving msg. ULONG flags Options:

Q_NOWAIT – Don’t wait for messages. Q_WAIT – Wait for messages.

ULONG timeout Ticks to wait. If timeout value is zero (0) and the Q_WAIT flag is set, then the call waits until a message arrives.

void * msg_buf Pointer to data buffer where the message will be copied.

ULONG buf_len Length of the message buffer. Linux ignores this parameter. There is no checking done to see if the user has the correct buffer length. The message will be copied based on its actual size to msg_buf.

ULONG * msg_len The message length value returned by the call.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid queue or memory pointer. ERR_QFULL Queue is full. ERR_TIMEOUT Time out waiting for a message when NOT

waiting. ERR_NOMSG No message in the queue when NOT

waiting. ERR_QKILLD Queue was deleted while waiting for a

message. ERR_STALEID Unable to suspend from non-thread

functions. ERR_BUFSIZ WARNING: Linux just checks to see if

buf_len is greater than four (4) and assumes the buffer size is ok and copies the data into this buffer.


Linux Functions Called OSC_Receive_From_Pipe -> TBD

Special Notes The parameter buf_len is ignored. The message will be copied to msg_buf based on its actual size, so make sure the application receive buffer is big enough to hold the message.


q_vbroadcast This API is NOT supported in this release. Sends a variable length message to each task that is waiting on the queue.

Parameters Parameter Meaning

Queue ID. void * msg_buf Pointer to data. ULONG msg_len The length of the message to send. ULONG *count Return a value indicating the number of

tasks that receives this message. This is not supported. A value of (-1) is always returned.

ULONG qid


Linux Functions Called INT_OSC_Broadcast_To_Pipe -> TBD

Special Notes Does not provide the value for the count variable, which indicates the number of tasks receiving this broadcast message.


q_vident This API is NOT SUPPORTED in this release. Gets the queue ID of the named variable message queue.

Parameters Parameter Meaning CHAR q_name Queue name for which the queue ID is

wanted. ULONG node The value for node should always be zero

(0) to indicate single processor mode. ULONG *qid The first queue ID that matches with the

q_name is returned.

Return Value Return Value Meaning EOK Successful. ERR_OBJNF Queue name not found. ERR_NODENO Node other than node=0 is not supported.

Linux Functions Called INT_OSC_Queue_Ident -> TBD

Special Notes No multiprocessor support, therefore the value for the node variable should always contain zero (0).


Semaphores

sm_create Creates a semaphore.

Parameters Parameter Meaning CHAR name[4] Four (4) byte semaphore object name. ULONG count Initial count value for the semaphore. ULONG flags Options:

SM_GLOBAL – Semaphore is addressable globally across multiple processors. This option is ignored. SM_LOCAL – Semaphore is addressable only in the local processor. SM_PRIOR – Tasks queued by task’s priority. SM_FIFO – Tasks queued by FIFO.

ULONG *smid Semaphore ID is returned by this call.

Return Value Return Value Meaning EOK Successful. ERR_NOMGB No memory for creating the semaphore

control block.

Linux Functions Called OSC_Allocate_Memory -> TBD OSC_Create_Semaphore -> TBD OSC_Deallocate_Memory -> TBD

Special Notes No multiprocessor support, so global semaphores are created in local node.


sm_delete Deletes the specified semaphore.

Parameters Parameter Meaning ULONG smid Semaphore ID is returned here.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid semaphore ID.

Linux Functions Called OSC_Delete_Semaphore -> TBD OSC_Deallocate_Memory -> TBD


sm_p Acquires or obtains a semaphore.

Parameters Parameter Meaning ULONG smid Semaphore ID is returned here. ULONG flags Options:

SM_WAIT – Block until semaphore is available. SM_NOWAIT – Non-blocking semaphore request.

ULONG timeout Expiration in ticks (valid only with the SM_WAIT option).

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid semaphore ID. ERR_TIMEOUT Timeout expired before semaphore can be

taken. ERR_NOSEM Semaphore unavailable (for NO_WAIT

option only). ERR_SKILLD Semaphore deleted while task is waiting.

Linux Functions Called OSC_Take_Semaphore -> TBD


sm_v Releases or gives up the semaphore.

Parameters Parameter Meaning ULONG smid Semaphore ID is returned here.


Linux Functions Called OSC_Give_Semaphore -> TBD


sm_ident This API is NOT SUPPORTED in this release. Obtains the semaphore ID for the named semaphore.

Parameters Parameter Meaning CHAR s_name[4] Four (4) byte semaphore name for which

the ID is required. ULONG node Node should always be zero (0) since there

is no multi-processor support. ULONG *smid The first semaphore ID that matches with

the s_name is returned.


Linux Functions Called INT_OSC_Semaphore_Ident -> TBD

Special Notes No multiprocessor support, therefore the value for the node variable must be zero (0).


Events

ev_asend Asynchronously sends events to the task. This support is available only in the pSOS™+m (multiprocessor kernel) product. OS Changer treats this function as ev_send.

Parameters Parameter Meaning ULONG tid ID of task to send the event to. ID cannot

be zero (0), since the calling task cannot send events to itself.

ULONG event Event(s) to send.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid task name or event group.

Linux Functions Called OSC_Set_Events -> TBD

Special Notes This function cannot be used within a task to send the events to itself.

No multiprocessor support, so this function will behave like Ev_send.


ev_receive Waits for an event to occur.

Parameters Parameter Meaning ULONG eventin Bit-encoded events to wait on. If the value is

zero (0), then this call reads the event flag’s value and provides it in the eventout variable, leaving the events pending.

ULONG flags EV_NOWAIT – Causes the function to return even if the event condition is not satisfied. EV_WAIT – The call blocks until the event condition is satisfied. EV_ANY – Wait for ANY of the desired bits to be satisfied (OR qualifier) before the call return. Events waited on are cleared when the call returns. EV_ALL – Wait for ALL of the desired bits to be satisfied (AND qualifier) before the call return. Events waited on are cleared when the call returns.

ULONG timeout Length of time to wait for the events before the call timeout (valid only with EV_WAIT option).

ULONG *eventout Event(s) received.

Return Value Return Value Meaning EOK Successful. ERR_TIMEOUT Requested events are not received before timeout. ERR_NOEVS Requested events are not received and the no-

wait flag set. ERR_OBJID Invalid task pointer or parameters or calling

function is not a task.

Linux Functions Called OSC_Current_Task_Id -> TBD OSC_Get_Events -> TBD


ev_send Allows the sending of signaling events to a specific task. A task sending events to itself is not allowed.

Parameters Parameter Meaning ULONG tid ID of task to send the event to. ID cannot be zero

(0), since the calling task cannot send events to itself.

ULONG event Event(s) to send.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid task name or event group.

Linux Functions Called OSC_Set_Events -> TBD

Special Notes This function cannot be used within a task to send the events to itself.


Signals

as_return void as_return(void)

This API is NOT supported. Returns from ASR – function does nothing – may be left for portability.

Parameters None

Return Value EOK - Always returns success (0).


Special Notes


as_catch This API is NOT supported. Specifies a signal handler for the calling task.

Parameters Parameter Meaning VOID (*signal handler)(VOID) Signals handler function to install. Mode The modes are described below:

T_PREEMPT – ASR can be preempted. T_NOPREEMPT – ASR cannot be preempted. T_NOTSLICE – ASR cannot be time sliced. T_TSLICE – ASR can be time sliced. T_ASR – ASR nesting enabled. T_NOASR – ASR nesting is disabled. T_USER – ASR runs in User mode. T_SUPV – ASR runs in supervisor mode.

Return Value Return Value Meaning EOK Always success.

Linux Functions Called OSC_Register_Signal_Handler -> TBD OSC_Control_Signals -> TBD

Special Notes No preemption or time slice support, so no stack frame is being built for ASR execution.


as_send This API is NOT supported. Sends an asynchronous signal to task. The signal gets OR'ed with others.

Parameters Parameter Meaning ULONG tid The task ID of the task to signal. ULONG signal_mask 32-bit signal mask (1 is set, 0 is unset).

Return Value Return Value Meaning EOK If successful. ERR_OBJID If <tid> is invalid. ERR_NOASR If target task has not installed an ASR. ERR_OBJDEL If signal was not sent due to invalid

<tid>. ERROR Some other errors

Linux Functions Called OSC_Send_Signals -> TBD


Device I/O Interface

de_init The de_init() call invokes the device init routine of a device driver specified by the dev argument. The device init routine can be used to perform device initialization functions that need to be done before the I/O operations can be performed on the device. The argument dev specifies the major and minor device numbers, which are stored in the upper and lower 16 bits, respectively. The argument iopb points to an I/O parameter block, the contents of which are driver-specific. The argument retval points to a variable that receives a driver-specific value returned by the driver.

Parameters Parameter Meaning unsigned long dev major/minor device number void *iopb I/O parameter block void *retval return value void **data_area device data area (not used)

Return Value Return Value Meaning EOK Successful ERR_IODN Illegal device major # ERR_NODR No driver provided


Special Notes


de_open The de_open() call invokes the device open routine of a device driver specified by the dev argument. The device open routine can be used to perform functions that need to be done before the I/O operations can be performed on the device. A device driver can also assign specific duties to the open routine that are not directly related to data transfer or device operations. For example, a device driver can use de_open() to enforce exclusive use of the device for all it’s read and/or write operations. The argument dev specifies the major and minor device numbers, which are stored in the upper and lower 16 bits, respectively. The argument iopb points to an I/O parameter block, the contents of which are driver-specific. The argument retval points to a variable that receives a driver-specific value returned by the driver.

Parameters Parameter Meaning unsigned long dev major/minor device number void *iopb I/O parameter block void *retval return value



Special Notes


de_read The de_read() call is used to read data from a device. It invokes the device read routine of the device driver specified by the dev argument. This service normally requires additional parameters contained in the I/O parameter block (like address of a data area to hold the data, number of data units to read, etc.). The argument dev specifies the major and minor device numbers, which are stored in the upper and lower 16 bits, respectively. The argument iopb points to an I/O parameter block, the contents of which are driver-specific. The argument retval points to a variable that receives a driver-specific value returned by the driver. For example, it can hold the actual number of data units read. .




Special Notes This call does NOT block the calling task for interrupt based devices, which is unlike how it is in pSOS. The driver routine needs to relinquish task control until the ISR completes the task and then it will resume the calling task.


de_write The de_write() call is used to write to a device. It invokes the device write routine of a device driver specified by the dev argument. This service normally requires the additional parameters contained in the I/O parameter block, such as the address of the user's output data and the number of data units to write. The argument dev specifies the major and minor device numbers, which are stored in the upper and lower 16 bits, respectively. The argument iopb points to an I/O parameter block, the contents of which are driver-specific. The argument retval points to a variable that receives a driver-specific value returned by the driver (the actual number of data units written).




Special Notes This call does NOT block the calling task for interrupt based devices, which is unlike how it is in pSOS. The driver routine needs to relinquish task control until the ISR completes the task and then it will resume the calling task.


de_cntrl The de_cntrl() call invokes the device control routine of a device driver specified by the dev argument. The functionality of device control routine depends entirely on the device driver implementation and can include anything that not be categorized under the other five I/O services. Typically, de_cntrl() for a device can be used to perform multiple input and output sub-functions. In such cases, extra parameters in the I/O parameter block can designate the sub-function. The argument dev specifies the major and minor device numbers, which are stored in the upper and lower 16 bits, respectively. The argument iopb points to an I/O parameter block, the contents of which are driver-specific. The argument retval points to a variable that receives a driver-specific value returned by the driver.




Special Notes


de_close The de_close() call invokes the device close routine of a device driver specified by the dev argument. The functionality of the device close routine is device-specific. The de_close() call, when used in conjunction with de_open(), can also be used to implement mutual exclusion for the device. In this case, de_close() can be used to signal the end of the critical region for the device operation. The argument dev specifies the major and minor device numbers, which are stored in the upper and lower 16 bits, respectively. The argument iopb points to an I/O parameter block, the contents of which are driver-specific. The argument retval points to a variable that receives a driver-specific value returned by the driver.




Special Notes


Timers

tm_wkafter Wakes up the calling task after so many clock ticks.

Parameters Parameter Meaning ULONG ticks Number of ticks to sleep.


Linux Functions Called OSC_Sleep_Task -> TBD


tm_evafter Sends events to calling task after specified interval.

Parameters Parameter Meaning ULONG ticks Clock ticks to wait before sending event. ULONG events Event lists. ULONG *tmid Timer ID returned and can be used by the

application to cancel the timer at any time. Applications need to cancel the timers implicitly to stop and remove them from the system.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Unable to use the tasks event handler

because you are probably not calling this function from the task.

ERR_NOTIMERS Unable to create the timer.

ERR_NOMGB Unable to create the control block. No memory is available.

Linux Functions Called OSC_Current_Task_Id -> TBD OSC_Allocate_Memory -> TBD OSC_Create_Timer -> TBD OSC_Deallocate_Memory -> TBD

Special Notes Implicit calls to tm_cancel have to be issued to stop and remove the timers from the system when the tasks are restarted or deleted from the system.


tm_evevery Sends events to calling tasks at specified intervals.

Parameters Parameter Meaning ULONG ticks Clock ticks to wait before sending event. ULONG events Event list. ULONG *tmid Timer ID returned and can be used by the

application to cancel the timer at any time. Applications need to cancel the timers implicitly to stop and remove them from the system.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Unable to use the tasks event handler

because you are probably not calling this function from the task.

ERR_NOTIMER Unable to create the timer.

ERR_NOMGB Unable to create the control block. No memory is available.

Linux Functions Called OSC_Current_Task_Id -> TBD OSC_Allocate_Memory -> TBD OSC_Create_Timer -> TBD OSC_Deallocate_Memory -> TBD

Special Notes Implicit calls to tm_cancel have to be issued to stop and remove the timers from the system when the tasks are restarted or deleted from the system.


tm_cancel Disables and deletes the specified timer.

Parameters Parameter Meaning ULONG tmid Timer ID of the timer to be disabled and

deleted.

Return Value Return Value Meaning EOK Successful. ERR_OBJID Invalid timer ID.

Linux Functions Called OSC_Control_Timer -> TBD OSC_Delete_Timer -> TBD OSC_Deallocate_Memory -> TBD


tm_set This API is NOT supported in the current Release. Sets system time and date.

Parameters Parameter Meaning ULONG date New year, month, date

Year – Bits 31 - 16 Month (1 - 12) – Bits 15 - 8 Day (1 - 31) – Bits 7 - 0

ULONG time New hour, minute, second Hour (0 - 23) – Bits 31 - 16 Minutes (0 - 59) – Bits 15 - 8 Seconds (0 - 59) – Bits 7 - 0

ULONG ticks Number of ticks from the last second. This parameter is ignored.

Return Value Return Value Meaning EOK Successful. ERR_ILLTIME Invalid time. ERR_ILLDATE Invalid date.

Linux Functions Called OSC_Set_Clock_Ticks -> TBD

Special Notes The parameter passed in the tick variable is ignored by tm_set.


tm_get This API is Not Supported in this Release. Gets system time and date.

Parameters Parameter Meaning ULONG *date New year, month, date

Year – Bits 31 - 16 Month (1 - 12) – Bits 15 - 8 Day (1 - 31) – Bits 7 - 0

ULONG *time New hour, minute, second Hour (0 - 23) – Bits 31 - 16 Minutes (0 - 59) – Bits 15 - 8 Seconds (0 - 59) – Bits 7 - 0

ULONG *ticks The number of ticks elapsed from last second. NOTE: OS Changer returns the value of the Linux clock tick and NOT the number of ticks elapsed from the last second.

Return Value Return Value Meaning EOK Successful. ERR_NOTIME Time and date were not set from the

system start up.

Linux Functions Called OSC_Get_Clock_Ticks -> TBD

Special Notes The value returned in the tick variable will be the Linux system clock counter instead of the tick count from the last sec.


tm_wkwhen Blocks a task until the specified time. NOT SUPPORTED.

Parameters Parameter Meaning ULONG *date New year, month, date. ULONG *time New hour, minute, second. ULONG *ticks New clock tick counter value.

Return Value Return Value Meaning ERR_NOT_SUPPORTED This function is NOT SUPPORTED.



tm_evwhen Sends an event to a task at specified time. NOT SUPPORTED.

Parameters Parameter Meaning ULONG *date New year, month, date. ULONG *time New hour, minute, second. ULONG *ticks New clock tick counter value. ULONG event Event bits to send. ULONG *tmid Timer ID.

Return Value Return Value Meaning ERR_NOT_SUPPORTED This function is NOT SUPPORTED.


Documents

pSOS to Linux OS Changer Reference Manual and Users’ Guide...This product comes in the form of a library providing support for pSOS™ kernel APIs integrated and optimized for Linux