Task Overview - Task Task Overview - Library The MDOS Library is the main system library giving tasks access to system functions. Task Attributes Task priority : 128 (normal priority) Task depends on : No other tasks/libraries Task Description Task description pending. Library Description To be written. Task History        08 September 2010 None No history found as yet...       Task Function Calls Here follows a list of functions supplied by this library with a brief description of each. By clicking on a function name, further information will be shown. Function Brief OS_Call Internal call to allow OS calls to make OS requests OS_Debug Display a debug value OS_DelayUS Short delay with micro-second level accuracy OS_Die Display a debug value then stop OS_FuncMain Function brief pending... OS_ISRClaim Claim an ISR OS_ISRRelease Release an ISR OS_MemAlloc Allocate a block of memory OS_MemAllocClr Allocate and zero a block of memory OS_MemCmp Perform a memory compare OS_MemCopy Perform a memory move OS_MemFindBlock Return the address of a custom memory block OS_MemFree Release a block of allocated memory OS_MemMove Perform a memory move OS_MemOperation Performs a myriad of memory operations OS_MemReAlloc Re-allocate a block of allocated memory OS_MemSet Fill a block of memory with a value OS_MessageCountPending Count number of pending messages OS_MessageGet Get next message from message queue OS_MessagePost Post a message OS_MessageSend Send a message OS_MessageSetBroadcastMask Specify a message mask for global messages OS_Null Makes a no-op call to OS OS_ResourceCheck Check if a named resource is in use OS_ResourceCreate Create a named resource OS_ResourceDestroy Destroy a named resource OS_ResourceLock Lock a named resource OS_ResourceUnlock Unlock a named resource OS_Sleep Put task to sleep for a number of milliseconds OS_SystemReboot Inform OS reboot the system OS_TaskCheckExists Check if a task exists OS_TaskCheckForRequired Check if a task exists and stop if it does not OS_TaskCreate Create a new task from task image in memory OS_TaskDestroy Destroy a named task OS_TaskExit Task informs OS that it is about to exit OS_TaskGetList Get start of task data link list OS_TaskGetPriority Returns the priority level of a named task OS_TaskGetState Get state of a task OS_TaskSetPriority Sets the priority level of a named task OS_TimerGetMonotonicTime Returns the number of milliseconds since startup OS_TimerSet Sets the task timer message period OS_Yield Allow another task to execute OS_Call Internal call to allow OS calls to make OS requests Function prototype  void OS_Call(                DWORD function  ); Input parameter(s)      DWORD function - function number for OS call     Return value      None       Purpose This is an internal call which routes all OS library functions to the OS kernel. History        08 November 2005 GJP Created  29 November 2005 GJP Added main OS call       Click here to report an error Back to top OS_Debug Display a debug value Function prototype  void OS_Debug(                 BYTE *text,                 DWORD val  ); Input parameter(s)      BYTE *text - text to display  DWORD val - value to display     Return value      None       Purpose This will display a 32bit hex debug value. History        19 April 2006 GJP Created       Click here to report an error Back to top OS_DelayUS Short delay with micro-second level accuracy Function prototype  void OS_DelayUS(                   DWORD us  ); Input parameter(s)      DWORD us - micro-second delay period     Return value      None       Purpose This will delay execution by a specified number of microseconds. No other tasks will execute during this delay, although IRQs are still fully operational. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_Die Display a debug value then stop Function prototype  void OS_Die(               BYTE *text,               DWORD val  ); Input parameter(s)      BYTE *text - text to display  DWORD val - value to display     Return value      None       Purpose This will display a 32bit hex debug value then stop. History        05 February 2009 GJP Created       Click here to report an error Back to top OS_FuncMain Function brief pending Function prototype  int OS_FuncMain(); Input parameter(s)      None       Return value      None       Purpose Function purpose description pending. History        26 February 2008 GJP Created       Click here to report an error Back to top OS_ISRClaim Claim an ISR Function prototype  BOOL OS_ISRClaim(                    BYTE isr,                    void *code  ); Input parameter(s)      BYTE isr - ISR number  void *code - address of code for ISR code     Return value      BOOL - completion status     Purpose This will allocated an ISR to an interrupt vector. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_ISRRelease Release an ISR Function prototype  void OS_ISRRelease(                      BYTE isr,                      BYTE *code  ); Input parameter(s)      BYTE isr - ISR number  void *code - address of code for ISR code     Return value      None       Purpose This will remove an ISR from an interrupt vector. History        08 November 2005 GJP Created  04 May 2008 GJP Now need to specify ISR code to release       Click here to report an error Back to top OS_MemAlloc Allocate a block of memory Function prototype  void *OS_MemAlloc(                     DWORD size  ); Input parameter(s)      DWORD size - size of memory to allocate     Return value      void * - address of allocated memory or null     Purpose This will allocate a block of memory of a given size and return the address of the block. If the request can not be met, then NULL is returned. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MemAllocClr Allocate and zero a block of memory Function prototype  void *OS_MemAllocClr(                        DWORD size  ); Input parameter(s)      DWORD size - size of memory to allocate     Return value      void * - address of allocated memory or null     Purpose This will allocate a block of memory of a given size and return the address of the block, which is zeroed. If the request can not be met, then NULL is returned. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MemCmp Perform a memory compare Function prototype  BYTE OS_MemCmp(                  void *dest,                  void *src,                  DWORD size  ); Input parameter(s)      void *dest - destination address of data  void *src - source address of data  DWORD size - size of data     Return value      BYTE - compare result     Purpose This will compare two blocks of memory, returning MEMOP_CMPSMALLER, MEMOP_CMPEQUAL or MEMOP_CMPLARGER accordingly. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MemCopy Perform a memory move Function prototype  void OS_MemCopy(                   void *dest,                   void *src,                   DWORD size  ); Input parameter(s)      void *dest - destination address of data  void *src - source address of data  DWORD size - size of data     Return value      None       Purpose This will copy a block of memory from one location to another. This function is not identical to OS_MemMove and will not take care of any overlaps of memory blocks. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MemFindBlock Return the address of a custom memory block Function prototype  void *OS_MemFindBlock(                         DWORD type  ); Input parameter(s)      DWORD typr - type of memory block     Return value      void * - address of block or NULL     Purpose This will find a custom memory block and return it's location in memory History        10 July 2009 GJP Created       Click here to report an error Back to top OS_MemFree Release a block of allocated memory Function prototype  void OS_MemFree(                   void *addr  ); Input parameter(s)      void *addr - block of memory to free     Return value      None       Purpose This will release a previously allocated block of memory created by OS_Alloc, OS_AllocClr and OS_ReAlloc. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MemMove Perform a memory move Function prototype  void OS_MemMove(                   void *dest,                   void *src,                   DWORD size  ); Input parameter(s)      void *dest - destination address of data  void *src - source address of data  DWORD size - size of data     Return value      None       Purpose This will move a block of memory from one location to another taking into account any memory block overlap. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MemOperation Performs a myriad of memory operations Function prototype  BYTE OS_MemOperation(                        void *dest,                        void *src,                        DWORD size,                        DWORD op  ); Input parameter(s)      void *dest - destination address of data  void *src - source address of data  DWORD size - size of data  DWORD op - control byte     Return value      BYTE - bitmap of result flags     Purpose This performs a number of memory operations from simple movement to arithmetic operations. It may be classed as a highly sophisticated bit blitter. History        08 November 2005 GJP Created  20 June 2008 GJP Now use a 32bit 'type' for transfers       Click here to report an error Back to top OS_MemReAlloc Re-allocate a block of allocated memory Function prototype  BYTE *OS_MemReAlloc(                       void *ptr,                       DWORD size  ); Input parameter(s)      void *ptr - address of memory to resize  DWORD size - new size of memory     Return value      void * - new address of resized memory or null     Purpose This will resize a block of memory. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MemSet Fill a block of memory with a value Function prototype  void OS_MemSet(                  void *dest,                  BYTE val,                  DWORD size  ); Input parameter(s)      void *dest - destination address of data  BYTE val - value to set memory to  DWORD size - size of data     Return value      None       Purpose This will fill a block of memory with a given byte value. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MessageCountPending Count number of pending messages Function prototype  DWORD OS_MessageCountPending(); Input parameter(s)      None       Return value      DWORD - number of pending messages     Purpose This will return the number of pending messages for the calling task. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MessageGet Get next message from message queue Function prototype  BOOL OS_MessageGet(                      MSG msg  ); Input parameter(s)      MSG msg - pointer to message to be sought     Return value      BOOL - TRUE if msg received else task must exit     Purpose This will return (and remove) the next message for the calling task from it's message queue. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MessagePost Post a message Function prototype  BOOL OS_MessagePost(                       BYTE *taskname,                       void *msg  ); Input parameter(s)      BYTE *taskname - name of task to post, or null for all  MSG *msg - actual message to post     Return value      BOOL - completion status     Purpose This will post a message to a task and return immediately. No results of the message will be returned and the message is placed in the task's message queue. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MessageSend Send a message Function prototype  BOOL OS_MessageSend(                       BYTE *taskname,                       void *msg  ); Input parameter(s)      BYTE *taskname - name of task to send, or null for all  MSG *msg - actual message to send     Return value      BOOL - completion status     Purpose This will send a task a message and wait for a reply. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_MessageSetBroadcastMask Specify a message mask for global messages Function prototype  void OS_MessageSetBroadcastMask(                                   DWORD message,                                   BOOL enable  ); Input parameter(s)      DWORD message - message to add or remove  BOOL enable - TRUE to add global message, FALSE to remove     Return value      None       Purpose This allows the calling task to set a mask of which global messages it will receive. This is for performance related issues as most tasks do not require the reception of global messages. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_Null Makes a no-op call to OS Function prototype  void OS_Null(); Input parameter(s)      None       Return value      None       Purpose This will make a call to the OS and return immediately. History        11 September 2008 GJP Created       Click here to report an error Back to top OS_ResourceCheck Check if a named resource is in use Function prototype  BOOL OS_ResourceCheck(                         BYTE *resource  ); Input parameter(s)      BYTE *resource - name of resource     Return value      BOOL - TRUE if claimed, else false     Purpose This will check if a named resource is currently claimed by a task. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_ResourceCreate Create a named resource Function prototype  BOOL OS_ResourceCreate(                          BYTE *resource  ); Input parameter(s)      BYTE *resource - name of resource     Return value      BOOL - creation status     Purpose This will create a named resource. If the resource already exists, the instance count of that resource is simply incremented. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_ResourceDestroy Destroy a named resource Function prototype  BOOL OS_ResourceDestroy(                           BYTE *resource  ); Input parameter(s)      BYTE *resource - name of resource     Return value      BOOL - destroy status     Purpose This will destroy a named resource if it is the only remaining instance of that resource else it will simply decrement the instance count of the resource. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_ResourceLock Lock a named resource Function prototype  void OS_ResourceLock(                        BYTE *resource  ); Input parameter(s)      BYTE *resource - name of resource     Return value      None       Purpose This will claim (thus block further claiments) of a named resource. If the resource is already claimed than the calling task is blocked. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_ResourceUnlock Unlock a named resource Function prototype  void OS_ResourceUnlock(                          BYTE *resource  ); Input parameter(s)      BYTE *resource - name of resource     Return value      None       Purpose This will release a named resource allowing other tasks to claim it. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_Sleep Put task to sleep for a number of milliseconds Function prototype  void OS_Sleep(                 DWORD ms  ); Input parameter(s)      DWORD ms - time in milliseconds to go to sleep     Return value      None       Purpose This will put the calling task to sleep for the specified number of milliseconds. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_SystemReboot Inform OS reboot the system Function prototype  void OS_SystemReboot(); Input parameter(s)      None       Return value      None       Purpose This will cause all tasks to close down and restart the the CPU in a clean fashion. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TaskCheckExists Check if a task exists Function prototype  BOOL OS_TaskCheckExists(                           BYTE *taskname  ); Input parameter(s)      BYTE *name - name of task to check     Return value      BOOL - TRUE if task exists, else FALSE     Purpose This will check if a named tasks exists and is running within the OS. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TaskCheckForRequired Check if a task exists and stop if it does not Function prototype  void OS_TaskCheckForRequired(                                BYTE *taskname  ); Input parameter(s)      BYTE *taskname - name of task     Return value      None       Purpose This will check if a task exists and if it does not, it will show an error and stop. History        05 February 2009 GJP Created       Click here to report an error Back to top OS_TaskCreate Create a new task from task image in memory Function prototype  BOOL OS_TaskCreate(                      void *taskdata  ); Input parameter(s)      void *taskdata - pointer to task in memory     Return value      BOOL - completion status     Purpose The will create a new task from a raw task image already residing in memory. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TaskDestroy Destroy a named task Function prototype  BOOL OS_TaskDestroy(                       BYTE *taskname  ); Input parameter(s)      BYTE *taskname - name of task to mark for destruction     Return value      BOOL - completion status     Purpose This will mark a task for destruction, informing the target task that it needs to shut down. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TaskExit Task informs OS that it is about to exit Function prototype  void OS_TaskExit(                    DWORD result  ); Input parameter(s)      None       Return value      None       Purpose This is called by a task to inform the OS that it has completed it's shut down procedure and may be deleted from memory. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TaskGetList Get start of task data link list Function prototype  CONTEXTDATA *OS_TaskGetList(); Input parameter(s)      None       Return value      CONTEXTDATA * - pointer to first task     Purpose This returns the first task in the task list, then further tasks may be enumerated using the 'next' field in the CONTEXTDATA structure. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TaskGetPriority Returns the priority level of a named task Function prototype  BYTE OS_TaskGetPriority(                           BYTE *taskname  ); Input parameter(s)      BYTE *taskname - name of task (or NULL for current task)     Return value      BYTE - priority level of task     Purpose This will return the task priority of the calling task or a named task. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TaskGetState Get state of a task Function prototype  BYTE OS_TaskGetState(                        BYTE *taskname  ); Input parameter(s)      BYTE *taskname - name of task     Return value      BYTE - task state     Purpose This will return the current state of a task, such as sleep, waiting message, sending message etc. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TaskSetPriority Sets the priority level of a named task Function prototype  void OS_TaskSetPriority(                           BYTE *taskname,                           BYTE priority  ); Input parameter(s)      BYTE *taskname - name of task (or NULL for current task)  BYTE priority - priority level of task     Return value      None       Purpose This will set the task priority of the calling task or a named task. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TimerGetMonotonicTime Returns the number of milliseconds since startup Function prototype  DWORD OS_TimerGetMonotonicTime(); Input parameter(s)      None       Return value      DWORD - millisecond count since startup     Purpose This will return the number of milliseonds since the OS last started. This is an unsigned 32bit number so will wrap about every XXX days. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_TimerSet Sets the task timer message period Function prototype  void OS_TimerSet(                    DWORD ms  ); Input parameter(s)      DWORD ms - interval in milliseconds to get timer msgs     Return value      None       Purpose This will set the calling task's timer message rate. If the period is set to zero, then no timer message are sent. History        08 November 2005 GJP Created       Click here to report an error Back to top OS_Yield Allow another task to execute Function prototype  void OS_Yield(); Input parameter(s)      None       Return value      None       Purpose The will cause the calling task to 'sleep' for zero milliseconds, allowing other tasks to 'breath'. History        08 November 2005 GJP Created       Click here to report an error Back to top

Back to top

Home   News   Shop   MDOS   Adelian   Luan   Acorn & RISC OS   Consultancy   Hosting   Support   Repository   Contact   Admin                  T and C   Privacy Statement Click here to report an error or fault with this page