Main Page Modules Alphabetical List Data Structures File List Data Fields Globals
IXP425 OS Services (IxOsServices) APIThis 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
|
|
#define IX_OSSERV_ETHB_MAP_SIZE
|
|
#define IX_OSSERV_EXP_BUS_CS1_MAP_SIZE
|
|
#define IX_OSSERV_EXP_BUS_CS4_MAP_SIZE
|
|
#define IX_OSSERV_EXP_BUS_MAP_SIZE
|
|
#define IX_OSSERV_EXP_REG_MAP_SIZE
|
|
#define IX_OSSERV_GPIO_MAP_SIZE
|
|
#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
|
|
#define IX_OSSERV_NPEB_MAP_SIZE
|
|
#define IX_OSSERV_NPEC_MAP_SIZE
|
|
#define IX_OSSERV_OSTS_MAP_SIZE
|
|
#define IX_OSSERV_PMU_MAP_SIZE
|
|
#define IX_OSSERV_QMGR_MAP_SIZE
|
|
#define IX_OSSERV_UART1_MAP_SIZE
|
|
#define IX_OSSERV_UART2_MAP_SIZE
|
|
#define IX_OSSERV_USB_MAP_SIZE
|
|
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
|
|
typedef pthread_mutex_t IxMutex
|
|
Enumeration Type Documentation
|
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:
-
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:
-
- Returns:
- None
|
PUBLIC void ixOsServYield |
( |
void |
|
) |
|
|
|
Yields execution of the current thread.
- Parameters:
-
- Returns:
- none
|
|