psos to Linux OSChanger

Transcription

1 psos to Linux OS Changer Reference Manual and Users Guide psos to Linux OSChanger Reference Manual and Users Guide Copyright (c) 2004 MapuSoft Technologies 1301 Azalea Road Mobile, AL 36693

2 psos to Linux OS Changer Reference Manual and Users Guide

3 psos to Linux OS Changer Reference Manual and Users Guide 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 MapuSoft TM 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 FAX support@mapusoft.com Copyright ( ) 2004, All Rights Reserved. The information detailed in this manual is subject to change. Last Revised: 7/1/2004

4 psos to Linux OS Changer Reference Manual and Users Guide

5 Contents 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 Porting applications from psos legacy code to Linux OS Changer Overview API Variations Error Handling API Reference v

6 psos to Linux OS Changer Reference Manual and Users Guide Initialization PS_Initialize SetUpDriver() InstallDrivers Release Information OSC_Release_Information Error Handling OSC_Fatal_Error Task Control t_create t_start t_mode t_restart t_ident t_suspend t_delete t_resume t_setpri t_setreg t_getreg Region Memory rn_create rn_delete rn_getseg rn_ident rn_retseg Partition Memory pt_create pt_delete pt_getbuf pt_ident pt_retbuf pt_sgetbuf Fixed Queues q_create q_delete q_send q_urgent q_receive q_broadcast q_ident Variable Queues q_vcreate... 59

7 psos to Linux OS Changer Reference Manual and Users Guide q_vdelete q_vsend q_vurgent q_vreceive q_vbroadcast q_vident Semaphores sm_create sm_delete sm_p sm_v sm_ident Events ev_asend ev_receive ev_send Signals as_return as_catch as_send Device I/O Interface de_init de_open de_read de_write de_cntrl de_close Timers tm_wkafter tm_evafter tm_evevery tm_cancel tm_set tm_get tm_wkwhen...91 tm_evwhen... 92

8 1

9 psos to Linux OS Changer Reference Manual and Users Guide Chapter 1 - Introduction 1 Introduction About OSChanger OSChanger and Linux OS Integration

10 psos to Linux OS Changer Reference Manual and Users Guide 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 a, b & c API compliance in the field because there were no specific changes are required or made to the underlying Linux product.

11

12 3

13 Chapter 2 Getting Started 2 Getting Started How to Use OSChanger OSChanger Library Initialization Linux Timer and Clock Initialization Memory Usage Conditional Compilations 4

14 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.

15 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.

16 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 = ; 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.

17 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.

18 Conditional Compilations Select the RTOS by setting the following compiler definition as follows: Compilation Flag 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 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 ARM_TOOLS Using ADS tools from ARM Ltd GNU_TOOLS MQX_TOOLS Using GNU Tools Using Metaware Tools from ARC International

19 Select the OS Changer components for your application use as follows: Compilation Flag INCLUDE_OSC_ANSI This flag is NOT supported under LINUX OS INCLUDE_OSC_IO INCLUDE_OSC_PSOS INCLUDE_OSC_VXWORKS INCLUDE_OSC_POSIX Define this flag if your application needs the OS Changer I/O API support Define this flag if your application needs to use the psos compatibility APIs (optional product) Define this flag if your application needs to use the VxWorks compatibility APIs (optional product) 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 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 OSC_DEBUG_INFO Enable error checking for debugging

20 Chapter 3 - Porting Guide 3 Porting Guide Porting applications from psos legacy code to Linux OS Changer Overview API Variations Error Handling Release Information API Reference 11

21 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.

22 Porting psos TM Applications to LINUX - Guidelines Chart A - Kernel APIs, interrupts and device drivers START CHECK 1 Does your application uses any psos kernel APIs' that are not supported by OSCHANGER? Yes Implement the unsupported APIs using LINUX No CHECK 2 Does your application uses any psos APIs' provided by OSCHANGER that are little different from the original APIs? Yes Modify your application to handle the differences No CHECK 3 Does your application require call-out routines functions provided by psos kernel? Yes Modify OSCHANGER and/or implement them using Linux alternatives No CHECK 4 Does your application configure the target hardware differently than what was validated by the new RTOS you have chosen? No Yes Modify the port specific code or BSP to make it work for your board. It is highly recommended toget a native demo application running on your target prior to porting CHECK 5 Are you using psos based device drivers? No Yes Use device wrapper functions to interact with the driver to minimize changes to application. Port the psos device driver to Linux CHECK 6 Are you using interrupt service routines that are unaware to or unmanaged by psos? Yes Port them to work under Linux No Go To Chart B

23 Porting psos TM Applications to Linux - Guidelines Chart B - Other Components START CHECK 1 Does your application uses pna+ networking component provided by psos? Yes Port API interfaces and drivers to Linux via using BSD socket interface APIs. If you prefer to use a third party stack for any reason, then make sure it will work under Linux No CHECK 2 Does your application uses phile file management APIs provided by psos? Yes Port API interfaces and drivers to Linux No CHECK 3 Does your application uses OpTIC graphics APIs provided by psos? Yes Port API interfaces and drivers to native or third party graphics product No CHECK 4 Does your application uses prepc+ library APIs provided by psos? Yes Utilize the CLIB provided by Linux. Check to make sure the CLIB APIs you use are re-entrant for your multi-tasking environment No HAPPY PORTING

24 OS Changer Overview The OS Changer contains the following modules, which can be found at the installation directory: Module OSCHANGER.H Description This header files include RTOS specific components and also components that is required for the application PS_OSCHANGER\PS_OSCHANGER.H PS_OSCHANGER\PS_I.C PS_OSCHANGER\PS_AS.C PS_OSCHANGER\PS_EV.C PS_OSCHANGER\PS_T.C PS_OSCHANGER\PS_PT.C PS_OSCHANGER\PS_RN.C PS_OSCHANGER\PS_Q.C PS_OSCHANGER\PS_SM.C PS_OSCHANGER\PS_TM.C PS_OSCHANGER\PS_DE.C OSC_LX\OSC_LL.C OSC_LX\OSC_LX.H OSC_LX\OSC_LX.C OSC_LX\OSC_LX_INIT.C OSC_NU\OSC_LX_USR.C DEMO\PS_OSCHANGER\PS_LX_INIT.C DEMO\PS_OSCHANGER\PS_DEMO.C DEMO\PS_OSCHANGER\PS_DVSERIAL.C DEMO\PS_OSCHANGER\PS_USR.C 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 Provides the psos OS Changer initialize function Provides psos signal handling APIs Provides psos event handling APIs Provides psos task handling APIs Provides psos partition memory management APIs Provides psos memory region management APIs Provides psos fixed and variable queue APIs Provides psos semaphore handling APIs Provides psos timer, time and date APIs Provides psos of device and driver APIs Provides link list manipulation OSC to Linux compile time mapping module OSC to Linux function mapping module OS initialization to start application - function main() User configurable module. Configure fatal error handler rountines to your needs User configurable Linux initialization module User condigurable module. Sample psos demo application that runs on Linux Sample psos device driver code 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.

25 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

26 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

27 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

28 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 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_cntl 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_read 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 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 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_init 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 k_fatal YES Use OSC_Fatal_Error instead

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

30 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 Unlimited queue is not supported. supported q_create Zero (0) length queues are The variable count should not be zero (0). not supported 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

31 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

32 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 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.

33 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 None None Special Notes

34 InstallDrivers Install driver handlers in psos IO table. unsigned short major_number void (*dev_init)() void (*dev_open)() void (*dev_close)() void (*dev_read)() void (*dev_write)() void (*dev_ioctl)() unsigned long rsvd1 unsigned long rsvd2 OSC_NULL Valid Memory pointer device major number device init procedure device open procedure device close procedure device read procedure device write procedure device control procedure Not used Not used Failed to set up drivers. A pointer that was incremented depending on memory usage from AvailMemPtr Special Notes

35 Release Information OSC_Release_Information Provides a string containing the OS Changer and the underlying RTOS release information. None Returns This routine returns a character pointer to a string that contains OS Changer and RTOS release information. Special Notes

36 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. CHAR * fmt ULONG arg1 ULONG arg2 ULONG arg3 ULONG arg4 ULONG arg5 ULONG arg6 Contains the description text of the error. If not zero (0), it will be the return code from a Linux kernel API call. Not used. Not used. Not used. Not used. Not used. None 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).

37 Task Control t_create Creates a task. CHAR name[4] ULONG priority ULONG superstk ULONG userstk ULONG flags ULONG *tid ERR_TINYSTK ERR_PRIOR ERR_NOSTK Four (4) byte name tag for the task. Valid ranges are Priority 1 is low, 255 is highest. Supervisor stack size. This value is ignored under Linux, instead kernel default used. User stack size. This value is ignored under Linux, instead kernel default used. 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-processor T_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. TCB ID Return Task ID number. Successful. Invalid stack size. Priority is out of range. No memory to allocate requested stack space. OSC_Allocate_Memory -> TBD

38 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.

39 t_start Starts a task. ULONG tid ULONG mode, void (*entrypt) ULONG targs[] TCB ID required. 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. Entry point for the task. Arguments for the task. ERR_OBJID Successful. Invalid Task ID. 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.

40 t_mode Gets or changes the calling task s execution mode. 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. ERR_OBJID Successful. Invalid Task ID. OSC_Current_Task_Id -> TBD Special Notes T_ISR flag to disable all interrupts while task is running is not supported.

41 t_restart Restarts the task. ULONG tid UNSIGNED targs[] ERR_OBJID TCB ID required. Arguments for the task Successful. Invalid Task ID. INT_OSC_Restart_Task ->TBD Special Notes

42 t_ident Gets the first task s ID to correspond to a task name. This API is NOT SUPPORTED in this release. CHAR t_name[4] ULONG node ULONG *tid Name of the task for which the ID is required. If t_name is NULL then current task s ID will be returned. Only value allowed is node = 0 for a local or single processor. The first task s ID that matches with the t_name input is returned by this call. ERR_OBJNF ERR_NODENO Successful. Task not found. Node other than node=0 is NOT supported. 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).

43 t_suspend Suspends the task permanently until the application resumes it explicitly via t_resume call. ULONG tid ERR_OBJNF 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. Successful. Task not found. OSC_Suspend_Task-> Special Notes

44 t_delete Deletes the task regardless of the task s state. ULONG tid ERR_OBJID TCB ID required. Successful. Task invalid. OSC_Current_Task_Id -> TBD OSC_Delete_Task -> TBD OSC_Delete_Event_Group -> TBD OSC_Deallocate_Memory -> TBD Special Notes

45 t_resume Removes suspension set by t_suspend call. ULONG tid TCB ID required. ERR_NOTSUSP ERR_OBJNF Successful. Task was not suspended before. Task not found. OSC_Current_Task_Id -> TBD OSC_Resume_Task-> TBD

46 t_setpri Gets the current value and/or changes the task priority dynamically. ULONG tid ULONG newprio ULONG *oldprio TCB ID required. tid = 0 means it is the current task. The priority value to be set. If newprio=0, then the function just returns the value of the task priority without changing it. Task's old priority. Returns the values of the old_priority. OSC_Current_Task_Id -> TBD OSC_Change_Task_Priority -> TBD

47 t_setreg Updates application registers in TCB. ULONG tid ULONG regnum ULONG regvalue TCB ID required. tid = 0 means it is the current task. Number of register to set. Value to set register to. Successful. None

48 t_getreg Retrieves application registers in TCB. ULONG tid ULONG regnum ULONG *regvalue TCB ID required. tid = 0 means it is the current task. Number of register to set. Value to set register to. Successful. None

49 Region Memory rn_create Creates a variable segment memory from the memory pool. CHAR name[4] void * addr ULONG length ULONG unit_size ULONG flags ULONG *rnid ULONG *asiz ERR_NOMGB Four (4) byte memory region or pool name. Starting memory address. Length of region in bytes. Unit of region memory allocation in bytes. OS Changer ignores this value, because Linux does not require this info. 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. Region ID returned by this call. Maximum memory that is available for allocation. This value is returned by this call. Successful. If unable to allocate message buffers. 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.

50 rn_delete Deletes a variable segment memory region/pool. ULONG rnid Region ID. 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. OSC_Delete_Memory_Pool -> TBD Special Notes Allows deletion of the region even while tasks are waiting on pending memory allocation requests.

51 rn_getseg Allocates a block of memory segment from the memory region / pool. ULONG rnid ULONG size ULONG flags ULONG timeout void ** segaddr ERR_NOSEG ERR_OBJID ERR_RNKILLD ERR_TIMEOUT Region ID. Length of memory segment in bytes. 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). Timeout in clock ticks. This is valid only with flag option RN_WAIT. Returned segment address. Successful. Unable to allocate message buffers. Invalid pool or input parameters. While waiting for memory, the region was deleted. Time out waiting for memory. OSC_Allocate_Memory -> TBD

52 rn_ident Gets the region identifier of the named region. This API is NOT SUPPORTED in this release. CHAR name[4] ULONG *rnid ERR_OBJNF INT_OSC_Dynamic_Pool_Ident -> Four (4) byte memory region or pool name for which the region ID is required. Return the first memory region ID value that matches with the name. Successful. Not found. TBD

53 rn_retseg Returns a block of memory segment to the region from which it was allocated. ULONG rnid void * segaddr ERR_OBJID Region ID. Segment address. Successful. Invalid pool and/or segment address. OSC_Deallocate_Memory -> TBD

54 Partition Memory pt_create Creates a memory partition of fixed size buffers. 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. ERR_NOMGB Successful. If unable to allocate message buffers. 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.

55 pt_delete Deletes a fixed block memory region/pool. ULONG ptid ERR_OBJID ERR_BUFINUSE Partition ID to delete. Successful. Invalid memory region / pool. Unable to delete. One or more buffers still in use. This option is not supported. OSC_Delete_Partition_Pool -> TBD Special Notes Allows deletion of the partition even while tasks are waiting on pending memory allocation requests.

56 pt_getbuf Gets a fixed size buffer from the memory partition. ULONG ptid void ** bufaddr ERR_NOBUF ERR_OBJID Partition ID. Returned buffer address. Successful. Unable to allocate message buffers. Invalid pool or input parameters. OSC_Allocate_Partition -> TBD

57 pt_ident Gets the partition ID of the named partition. This API is NOT SUPPORTED in this release. CHAR name[4] ULONG node ULONG *ptid ERR_NODENO ERR_OBJNF INT_OSC_Part_Ident -> Four (4) byte memory region or pool name. Multiprocessor option is not supported. The node value should always be zero (0). Return the first memory region ID that corresponds with the name. Successful. Invalid node. Invalid pool or input parameters. TBD

58 pt_retbuf Returns a block of memory from the memory region / pool. ULONG ptid void * bufaddr Region ID. buffer address. ERR_OBJID Successful. Invalid pool or buffer addr. OSC_Deallocate_Partition -> TBD

59 pt_sgetbuf Gets a memory buffer from fixed block along with returning both a physical and logical address. ULONG ptid void ** paddr void ** laddr ERR_OBJID Partition ID. Physical address. MMU not supported. The value will be same as paddr. Successful. Invalid pool or buffer addr. pt_getbuf -> TBD Special Notes

60 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). CHAR name[4] ULONG count ULONG flags ULONG *qid ERR_NOMGB Four (4) byte queue name. Maximum number of queue elements. The value for count = 0 indicates it is a zero (0) length queue; therefore, it is not supported. 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. Queue ID returned by this call. Successful. Unable to allocate message buffers.

61 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).

62 q_delete Deletes a fixed message queue. ULONG qid ERR_TATQDEL ERR_TATQDEL Queue ID for deletion. Successful. Tasks are still waiting on the queue. This option is not supported. There are still undelivered messages in the queue. This option is not supported. 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.

63 q_send Sends a fixed length message to the message queue. ULONG qid ULONG msg_buf[4] ERR_OBJID ERR_OBJDEL ERR_QFULL OSC_Send_To_Queue -> TBD Queue ID. Pointer to 16 byte data. Successful. Invalid queue or memory pointer. Queue already deleted. Queue is full.

64 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. ULONG qid ULONG msg_buf[4] Queue ID. Pointer to 16 byte data. ERR_OBJID ERR_OBJDEL ERR_QFULL OSC_Send_To_Front_Of_Queue -> TBD Successful. Invalid queue or memory pointer. Queue already deleted. Queue is full.

65 q_receive Receives a fixed length message from the message queue. ULONG qid ULONG flags ULONG timeout ULONG msg_buf[4] Queue ID for receiving messages. Options: Q_NOWAIT Do not wait for messages. Q_WAIT Wait for messages. 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. Pointer to 16 data buffer where the received message is copied. ERR_OBJID ERR_QFULL ERR_TIMEOUT ERR_NOMSG ERR_QKILLD OSC_Receive_From_Queue -> TBD Successful. Invalid queue or memory pointer. Queue is full. Time out waiting for a message (when Q_WAIT is set along with a timeout value). No message in the queue (when flag Q_NOWAIT is set). Queue was deleted while waiting for a message.

66 q_broadcast This API is NOT supported. Sends a fixed length message to each task that is waiting on the queue. ULONG qid ULONG msg_buf[4] ULONG *count Queue ID. Pointer to 16 byte message data to send. Return a value indicating the number of tasks that receives this message. This is not supported. A value of (-1) is always returned. Successful. ERR_OBJID Invalid queue or memory pointer. ERR_OBJDEL Queue already deleted. ERR_QFULL Queue is full. 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.

67 q_ident Gets the queue ID of the named fixed message queue. This API is NOT SUPPORTED in this release. CHAR q_name ULONG node ULONG *qid Queue name for which the queue ID uses. The value for the node should always be zero (0) to indicate single processor mode. The first queue ID that matches with the q_name is returned. ERR_OBJNF ERR_NODENO Successful. Queue name not found. This will be returned if node value is not zero (0). INT_OSC_Queue_Ident -> TBD Special Notes No multiprocessor support, therefore the value for the node variable should always be zero (0).

68 Variable Queues q_vcreate Creates a fixed length message queue of the user defined number of messages. CHAR name[4] ULONG flags ULONG count ULONG maxlength ULONG *qid Four (4) character long queue name. 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. Maximum number of queue elements. The value for count = 0 indicates it is a zero (0) length queue; therefore, it is not supported. Maximum size of an individual message element (in bytes). Queue ID returned by this call.