Main Page Modules Alphabetical List Data Structures File List Data Fields Globals # IXP425 OS Services (IxOsServices) API This service provides a very thin layer of OS dependency services. More...
## Defines
#define | IX_OSSERV_QMGR_MAP_SIZE
| Queue Manager map size.
#define | IX_OSSERV_EXP_REG_MAP_SIZE
| Exp Bus Registers map size.
#define | IX_OSSERV_UART1_MAP_SIZE
| UART1 map size.
#define | IX_OSSERV_UART2_MAP_SIZE
| UART2 map size.
#define | IX_OSSERV_PMU_MAP_SIZE
| PMU map size.
#define | IX_OSSERV_OSTS_MAP_SIZE
| OS Timers map size.
#define | IX_OSSERV_NPEA_MAP_SIZE
| NPE A map size.
#define | IX_OSSERV_NPEB_MAP_SIZE
| NPE B map size.
#define | IX_OSSERV_NPEC_MAP_SIZE
| NPE C map size.
#define | IX_OSSERV_ETHA_MAP_SIZE
| Eth A map size.
#define | IX_OSSERV_ETHB_MAP_SIZE
| Eth B map size.
#define | IX_OSSERV_USB_MAP_SIZE
| USB map size.
#define | IX_OSSERV_GPIO_MAP_SIZE
| GPIO map size.
#define | IX_OSSERV_EXP_BUS_MAP_SIZE
| Expansion bus map size.
#define | IX_OSSERV_EXP_BUS_CS1_MAP_SIZE
| CS1 map size.
#define | IX_OSSERV_EXP_BUS_CS4_MAP_SIZE
| CS4 map size.
#define | IX_OSSERV_MEM_MAP(requestedPhysicalAddress, size)
| Maps an I/O memory zone.
#define | IX_OSSERV_MEM_UNMAP(requestedVirtualAddress)
| unmaps a previously mapped I/O memory zone
#define | IX_OSSERV_MMAP_VIRT_TO_PHYS_TRANSLATION(virtualAddress)
| provides a mapped memory-aware virtual to physical translation
## Typedefs
typedef int | IX_IRQ_STATUS
| Defines flag to indicate IRQ status.
typedef SEM_ID | IxMutex
| Mutex object.
typedef SEM_ID | IxFastMutex
| Fast mutex object.
## Enumerations
enum | IxOsServTraceLevels { LOG_NONE, LOG_USER, LOG_FATAL, LOG_ERROR, LOG_WARNING, LOG_MESSAGE, LOG_DEBUG1, LOG_DEBUG2, LOG_DEBUG3, LOG_ALL }
| Trace levels. More...
## Functions
PUBLIC IX_STATUS | ixOsServIntBind (int level, void(*routine)(void *), void *parameter)
| binds a routine to a hardware interrupt
PUBLIC IX_STATUS | ixOsServIntUnbind (int level)
| unbinds a routine from a hardware interrupt
PUBLIC int | ixOsServIntLock (void)
| locks out IRQs
PUBLIC void | ixOsServIntUnlock (int lockKey)
| unlocks IRQs
PUBLIC int | ixOsServIntLevelSet (int level)
| sets the interrupt level
PUBLIC IX_STATUS | ixOsServMutexInit (IxMutex *mutex)
| initializes a mutex
PUBLIC IX_STATUS | ixOsServMutexLock (IxMutex *mutex)
| locks the given mutex
PUBLIC IX_STATUS | ixOsServMutexUnlock (IxMutex *mutex)
| unlocks the given mutex
PUBLIC IX_STATUS | ixOsServMutexDestroy (IxMutex *mutex)
| destroys a mutex object
PUBLIC IX_STATUS | ixOsServFastMutexInit (IxFastMutex *mutex)
| initializes a fast mutex
PUBLIC IX_STATUS | ixOsServFastMutexTryLock (IxFastMutex *mutex)
| attempts to lock the fast mutex object
PUBLIC IX_STATUS | ixOsServFastMutexUnlock (IxFastMutex *mutex)
| unlocks the fast mutex object
PUBLIC int | ixOsServLog (int level, char *format, int arg1, int arg2, int arg3, int arg4, int arg5, int arg6)
| logs a formatted message
PUBLIC int | ixOsServLogLevelSet (int level)
| sets the logging level
PUBLIC void | ixOsServSleep (int microseconds)
| execution block for a number of microseconds
PUBLIC void | ixOsServTaskSleep (int milliseconds)
| preemptive execution block for a number of milliseconds
PUBLIC unsigned int | ixOsServTimestampGet (void)
| used to retrieve the system timestamp
PUBLIC void | ixOsServUnload (void)
| Used to un-map memory.
PUBLIC void | ixOsServYield (void)
| Yields execution of the current thread.
## Detailed Description This service provides a very thin layer of OS dependency services. This file contains the API to the functions which are some what OS dependant and would require porting to a particular OS. A primary focus of the component development is to make them as OS independent as possible. All other components should abstract their OS dependency to this module. Services overview Trace Service - a simple debugging mechanism, with compile time debug trace level (depends on existent OS logging feature e.g. in Linux use kprintf, in VxWorks logMsg) Mutual Exclusion interrupt binding and locking mechanisms mutex locks and fast mutexes Timer Services timed delays, busy loop - microsecond granularity timed delays, OS dependent yielding - millisecond granularity timestamp measurements - XScale core clock granularity ## OsServices I/O Memory Allocation and Access Routines List of OSes and operating modes supported: (Please update the list when adding a new OS or mode) VxWorks BE VxWorks LE Linux BE ### Usage Information: `IxOsServicesMemAccess.h` defines OS/Endianess mode, memory mapped I/O access macros, NPE-shared memory routines, SDRAM coherency mode, default component coherency mode and static/dynamic memory mapping for every component. The symbols defined below can be used and some overriden in the component-specific section of IxOsServicesComponents.h. OS/Endianess defines: One of the following symbols will be defined: IX_OSSERV_VXWORKS_BE - component is compiled for VxWorks Big Endian IX_OSSERV_VXWORKS_LE - component is compiled for VxWorks Little Endian IX_OSSERV_LINUX_BE - component is compiled for Linux Big Endian SDRAM coherency mode: One of the following symbols will be defined: IX_SDRAM_BE - SDRAM is in Big Endian mode (default for Big Endian builds) IX_SDRAM_LE_ADDRESS_COHERENT - SDRAM is in Little Endian, Address Coherent Mode (not supported by current software) IX_SDRAM_LE_DATA_COHERENT - SDRAM is in Little Endian, Data Coherent Mode (default for Little Endian builds) Static/dynamic memory mapping: IX_STATIC_MEMORY_MAP - component uses statically I/O mapped memory (default) IX_DYNAMIC_MEMORY_MAP - component uses OS-specific dynamically mapped I/O memory (define this in the component specific section of IxOsServicesComponents.h to override the previous default value) Component coherency mode (define or override defaults in the component section of IxOsServicesComponents.h): CSR_BE_MAPPING - component uses I/O memory in Big Endian mode (default in Big Endian Builds) CSR_LE_ADDRESS_COHERENT_MAPPING - component uses I/O memory in Little Endian, Address Coherent mode CSR_LE_DATA_COHERENT_MAPPING - component uses I/O memory in Little Endian, Data Coherent mode CSR_NO_MAPPING - component does not use I/O memory (I/O read/write macros are not available) ### Macros for memory mapped I/O access: Unless CSR_NO_MAPPING is defined, each component will have access to the following set of macros for reading and writing word (32 bit), short (16 bit) and byte (8 bits) data. The macros will perform all the necessary endianess conversions and use appropriate read and write functions in OSes where this is required. The addresses (wAddr, sAddr, bAddr) should be volatile 32-bit pointers to UINT32, UINT16 and UINT8 respectively. The data (wData, sData, bData) should be UINT32, UINT16 and respectively UINT8 values. IX_OSSERV_READ_LONG(wAddr) - returns the 32-bit value at address wAddr IX_OSSERV_READ_SHORT(sAddr) - returns the 16-bit value at address sAddr IX_OSSERV_READ_BYTE(bAddr) - returns the 8-but value at address bAddr IX_OSSERV_WRITE_LONG(wAddr, wData) - writes the 32-bit wData at address wAddr IX_OSSERV_WRITE_SHORT(sAddr, sData) - writes the 16-bit sData at address sAddr IX_OSSERV_WRITE_BYTE(bAddr, bData) - writes the 8-bit bData at address bAddr ### Macros for sharing data with the NPEs: Each component will have access to the following set of macros for reading and writing word (32 bit) and short (16 bit) data, plus a macro for copying within SDRAM an array of words to be shared with an NPE. The macros will perform all the necessary endianess conversions depending on the SDRAM endianess and coherency mode to guarantee correct sharing of data between XScale components and NPEs. The addresses (wAddr, sAddr, wSrcAddr and wDestAddr) should be 32-bit pointers to UINT32 and UINT16 respectively (volatility is NOT required). The data (wData and sData) should be UINT32 and respectively UINT16 values. The word count for the copy macro (wCount) should be a UINT32 value. IX_OSSERV_READ_NPE_SHARED_LONG(wAddr) - returns the 32-bit value written by the NPE at address wAddr IX_OSSERV_READ_NPE_SHARED_SHORT(sAddr) - returns the 16-bit value written by the NPE at address sAddr IX_OSSERV_WRITE_NPE_SHARED_LONG(wAddr, wData) - writes 32-bit wData to be read by the NPE at address wAddr IX_OSSERV_WRITE_NPE_SHARED_SHORT(sAddr, sData) - writes 16-bit sData to be read by the NPE at address sAddr IX_OSSERV_COPY_NPE_SHARED_LONG_ARRAY(wDestAddr, wSrcAddr, wCount) - copies wCount 32-bit words shared with an NPE from wSrcAddr to wDestAddr IX_OSSERV_SWAP_NPE_SHARED_LONG(wData) - returns the correctly converted (if necessary) 32-bit value between NPE and SDRAM representation ## Define Documentation
#define IX_OSSERV_ETHA_MAP_SIZE
| Eth A map size. Definition at line 71 of file IxOsServicesMemMap.h.
#define IX_OSSERV_ETHB_MAP_SIZE
| Eth B map size. Definition at line 72 of file IxOsServicesMemMap.h.
#define IX_OSSERV_EXP_BUS_CS1_MAP_SIZE
| CS1 map size. Definition at line 76 of file IxOsServicesMemMap.h.
#define IX_OSSERV_EXP_BUS_CS4_MAP_SIZE
| CS4 map size. Definition at line 77 of file IxOsServicesMemMap.h.
#define IX_OSSERV_EXP_BUS_MAP_SIZE
| Expansion bus map size. Definition at line 75 of file IxOsServicesMemMap.h.
#define IX_OSSERV_EXP_REG_MAP_SIZE
| Exp Bus Registers map size. Definition at line 63 of file IxOsServicesMemMap.h.
#define IX_OSSERV_GPIO_MAP_SIZE
| GPIO map size. Definition at line 74 of file IxOsServicesMemMap.h.
#define IX_OSSERV_MEM_MAP | ( | requestedPhysicalAddress,
|  | size |  | ) |
  | Maps an I/O memory zone. Parameters:
  requestedAddress | UINT32 (in) - physical address to map
  size | UINT32 (in) - size of map (should be large enough to hold the largest offset access made in this zone)
This macro maps an I/O mapped physical memory zone of the given size into a virtual memory zone accessible by the caller and returns a cookie - the start address of the virtual memory zone. IX_MMU_PHYS_TO_VIRT_TRANSLATION should NOT therefore be used on the returned virtual address. The memory zone should be unmapped using IX_OSSERV_MEM_UNMAP once the caller has finished using this zone (e.g. on driver unload) using the cookie as parameter. The IX_OSSERV_READ/WRITE_LONG/SHORT macros should be used to read and write the mapped memory, adding the necessary offsets to the address cookie. Warning: Not to be called from interrupt level Note: The size parameter is only used for identifying a suitable (i.e. large enough) map in the global memory map (ixOsServGlobalMemoryMap). It is NOT used to actually map the memory zone. Instead, the zone indicated in the global memory map is used. Mapping will work only if the zone is predefined in the global memory map. Returns: the mapped virtual address or NULL if the operation could not be completed. This virtual address (cookie) has to be saved and used to unmap the memory zone during any clean-up or unload operation, using the IX_OSSERV_MEM_UNMAP macro. Definition at line 215 of file IxOsServicesMemMap.h.
#define IX_OSSERV_MEM_UNMAP | ( | requestedVirtualAddress |  | ) |
  | unmaps a previously mapped I/O memory zone Parameters:
  requestedAddress | UINT32 (in) - cookie (virtual address) to unmap
This macro unmaps a previously mapped I/O memory zone using the cookie obtained in the mapping operation. The memory zone in question becomes unavailable to the caller once unmapped and the cookie should be discarded. This macro cannot fail if the given parameter is correct and does not return a value. Warning: Not to be called from interrupt level Definition at line 237 of file IxOsServicesMemMap.h.
#define IX_OSSERV_MMAP_VIRT_TO_PHYS_TRANSLATION | ( | virtualAddress |  | ) |
  | provides a mapped memory-aware virtual to physical translation Parameters:
  virtualAddress | UINT32 (in) - cookie (virtual address) to translate
This macro searches through the global memory mapped for a virtualAddress match; if found, it will return the physical address defined in the map. Otherwise it will default to IX_MMU_VIRTUAL_TO_PHYSICAL_TRANSLATION. Returns: the physical address translation Definition at line 253 of file IxOsServicesMemMap.h.
#define IX_OSSERV_NPEA_MAP_SIZE
| NPE A map size. Definition at line 68 of file IxOsServicesMemMap.h.
#define IX_OSSERV_NPEB_MAP_SIZE
| NPE B map size. Definition at line 69 of file IxOsServicesMemMap.h.
#define IX_OSSERV_NPEC_MAP_SIZE
| NPE C map size. Definition at line 70 of file IxOsServicesMemMap.h.
#define IX_OSSERV_OSTS_MAP_SIZE
| OS Timers map size. Definition at line 67 of file IxOsServicesMemMap.h.
#define IX_OSSERV_PMU_MAP_SIZE
| PMU map size. Definition at line 66 of file IxOsServicesMemMap.h.
#define IX_OSSERV_QMGR_MAP_SIZE
| Queue Manager map size. Definition at line 62 of file IxOsServicesMemMap.h.
#define IX_OSSERV_UART1_MAP_SIZE
| UART1 map size. Definition at line 64 of file IxOsServicesMemMap.h.
#define IX_OSSERV_UART2_MAP_SIZE
| UART2 map size. Definition at line 65 of file IxOsServicesMemMap.h.
#define IX_OSSERV_USB_MAP_SIZE
| USB map size. Definition at line 73 of file IxOsServicesMemMap.h.
## Typedef Documentation
typedef int IX_IRQ_STATUS
| Defines flag to indicate IRQ status. Definition at line 96 of file IxOsServices.h.
typedef pthread_mutex_t IxFastMutex
| Fast mutex object. Definition at line 115 of file IxOsServices.h.
typedef pthread_mutex_t IxMutex
| Mutex object. Definition at line 102 of file IxOsServices.h.
## Enumeration Type Documentation
enum IxOsServTraceLevels
  | Trace levels. Enumeration values:
  LOG_NONE | No trace level.
  LOG_USER | Set trace level to user.
  LOG_FATAL | Set trace level to fatal.
  LOG_ERROR | Set trace level to error.
  LOG_WARNING | Set trace level to warning.
  LOG_MESSAGE | Set trace level to message.
  LOG_DEBUG1 | Set trace level to debug1.
  LOG_DEBUG2 | Set trace level to debug2.
  LOG_DEBUG3 | Set trace level to debug3.
  LOG_ALL | Set trace level to all.
Definition at line 135 of file IxOsServices.h.
## Function Documentation
PUBLIC IX_STATUS ixOsServFastMutexInit | ( | IxFastMutex * | mutex | ) |
  | initializes a fast mutex Parameters:
  mutex | IxFastMutex * (in) - pointer to the mutex object
Initializes a fast mutex, placing it in "unlocked" state. Can be called from interrupt level: yes Returns: IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
PUBLIC IX_STATUS ixOsServFastMutexTryLock | ( | IxFastMutex * | mutex | ) |
  | attempts to lock the fast mutex object Parameters:
  mutex | IxFastMutex * (in) - pointer to the mutex object
If the mutex is in "unlocked" state it becomes locked and the function returns "IX_SUCCESS". If the mutex is already locked the function returns immediately with a IX_FAIL result. Can be called from interrupt level: yes Returns: IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
PUBLIC IX_STATUS ixOsServFastMutexUnlock | ( | IxFastMutex * | mutex | ) |
  | unlocks the fast mutex object Parameters:
  mutex | IxFastMutex * (in) - pointer to the mutex object
Unlocks the given mutex object if locked, otherwise returns an error. Can be called from interrupt level: yes Returns: IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
PUBLIC IX_STATUS ixOsServIntBind | ( | int | level,
|  | void(* | routine)(void *),
|  | void * | parameter
| ) |
  | binds a routine to a hardware interrupt Parameters:
  level | int (in) - interrupt level to bind to
  routine | void (*)(void *) (in) - routine to connect
  parameter | void * (in) - parameter to pass to the routine when called
This functions binds the specified C routine to an interrupt level. When called, the "parameter" value will be passed to the routine. Can be called from interrupt level: no Returns: IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
PUBLIC int ixOsServIntLevelSet | ( | int | level | ) |
  | sets the interrupt level Parameters:
  level | int (in) - new interrupt level
This routine changes the interrupt mask in the status register to take on the value specified by level. Interrupts are locked out at or, depending on the implementation, below that level. Can be called from interrupt level: yes Returns: the previous interrupt level Warning: Do not call system functions when interrupts are locked
PUBLIC int ixOsServIntLock | ( | void |  | ) |
| locks out IRQs This function disables IRQs, returning a lock key which can be used later with ixOsServIntUnlock to re-enable the IRQs. Can be called from interrupt level: yes Returns: a lock key used by ixOsServIntUnlock to unlock IRQs Warning: Do not call system routines when IRQs are locked
PUBLIC IX_STATUS ixOsServIntUnbind | ( | int | level | ) |
  | unbinds a routine from a hardware interrupt Parameters:
  vector | int (in) - interrupt level to unbind from
This function unbinds from an interrupt level a C routine previously bound with ixOsServIntBind Can be called from interrupt level: no Returns: IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
PUBLIC void ixOsServIntUnlock | ( | int | lockKey | ) |
  | unlocks IRQs Parameters:
  lockKey | int (in) - lock key previously obtained with ixOsServIntLock()
This function reenables the IRQs locked out by ixOsServIntLock(). Can be called from interrupt level: yes
PUBLIC int ixOsServLog | ( | int | level,
|  | char * | format,
|  | int | arg1,
|  | int | arg2,
|  | int | arg3,
|  | int | arg4,
|  | int | arg5,
|  | int | arg6
| ) |
  | logs a formatted message Parameters:
  level | int (in) - trace level
  format | char * (in) - format string, similar to printf()
  arg1 | int (in) - first argument to display
  arg2 | int (in) - second argument to display
  arg3 | int (in) - third argument to display
  arg4 | int (in) - fourth argument to display
  arg5 | int (in) - fifth argument to display
  arg6 | int (in) - sixth argument to display
This function logs the specified message via the logging task. It is similar to printf(), however it requires a log level and a fixed number of arguments. Unless called with the LOG_USER log level it will prefix the user message with a tag string like "[debug2]". Can be called from interrupt level: yes Returns: the number of characters written
PUBLIC int ixOsServLogLevelSet | ( | int | level | ) |
  | sets the logging level Parameters:
  level | int (in) - logging level
This function sets the maximum level allowed for logging. Setting it to LOG_WARNING will disable all levels like LOG_MESSAGE, LOG_DEBUG1 etc. It returns the previous level which can be useful for restoring log states. Can be called from interrupt level: yes Returns: the previous logging level
PUBLIC IX_STATUS ixOsServMutexDestroy | ( | IxMutex * | mutex | ) |
  | destroys a mutex object Parameters:
  mutex | IxMutex * (in) - pointer to mutex to destroy
Can be called from interrupt level: no Destroys the mutex object, freeing the resources it might hold.
PUBLIC IX_STATUS ixOsServMutexInit | ( | IxMutex * | mutex | ) |
  | initializes a mutex Parameters:
  mutex | IxMutex * (in) - pointer to mutex to initialize
Initializes the given mutex (MUTual EXclusion device) Can be called from interrupt level: no Returns: IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
PUBLIC IX_STATUS ixOsServMutexLock | ( | IxMutex * | mutex | ) |
  | locks the given mutex Parameters:
  mutex | IxMutex * (in) - pointer to mutex to lock
If the mutex is unlocked it becomes locked and owned by the caller, and the function returns immediately. If the mutex is already locked calling this function will suspend the caller until the mutex is unlocked. Can be called from interrupt level: no Returns: IX_SUCCESS if the operation succeeded or IX_FAIL otherwise Warning: Two or more consecutive calls from the same thread of ixOsServMutexLock() are likely to deadlock the calling thread. Mutexes are NOT recursive.
PUBLIC IX_STATUS ixOsServMutexUnlock | ( | IxMutex * | mutex | ) |
  | unlocks the given mutex Parameters:
  mutex | IxMutex * (in) - pointer to mutex to unlock
Unlocks the given mutex, returning it to the "unlocked" state. If the mutex was not locked an error is returned. Can be called from interrupt level: yes Returns: IX_SUCCESS if the operation succeeded or IX_FAIL otherwise
PUBLIC void ixOsServSleep | ( | int | microseconds | ) |
  | execution block for a number of microseconds Parameters:
  microseconds | int (in) - delay to block execution for
This function blocks the calling task using a timed busy loop. Can be called from interrupt level: yes, except for the first invocation
PUBLIC void ixOsServTaskSleep | ( | int | milliseconds | ) |
  | preemptive execution block for a number of milliseconds Parameters:
  milliseconds | int (in) - delay to block execution for
This function blocks the calling task using an OS-dependent preemptive timed delay. Can be called from interrupt level: no
PUBLIC int ixOsServTimestampGet | ( | void |  | ) |
| used to retrieve the system timestamp Can be called from interrupt level: yes, except for the first invocation Returns: the current timestamp value
PUBLIC void ixOsServUnload | ( | void |  | ) |
  | Used to un-map memory. Parameters:
  None |
Returns: None
PUBLIC void ixOsServYield | ( | void |  | ) |
  | Yields execution of the current thread. Parameters:
  none |
Returns: none
Automatically generated from sources. © Intel Corp. 2003