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

  1. 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)
  2. Mutual Exclusion
    • interrupt binding and locking mechanisms
    • mutex locks and fast mutexes
  3. 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