VxWorks API Reference : USB libraries
ossLib [USB] - O/S-independent services for vxWorks
ossStatus( ) - Returns OK or ERROR and sets errno based on status
ossShutdown( ) - Shuts down ossLib
ossThreadCreate( ) - Spawns a new thread
ossThreadDestroy( ) - Attempts to destroy a thread
ossThreadSleep( ) - Voluntarily relinquishes the CPU
ossSemCreate( ) - Creates a new semaphore
ossSemDestroy( ) - Destroys a semaphore
ossSemGive( ) - Signals a semaphore
ossSemTake( ) - Attempts to take a semaphore
ossMutexCreate( ) - Creates a new mutex
ossMutexDestroy( ) - Destroys a mutex
ossMutexTake( ) - Attempts to take a mutex
ossMutexRelease( ) - Releases (gives) a mutex
ossPartSizeGet( ) - Retrieves the size of the USB memory partition.
ossPartSizeSet( ) - Sets the the initial size of the USB memory partition.
ossPartIdGet( ) - Retrieves the partition ID of USB memory partition.
ossMemUsedGet( ) - Retrieves amount of memory currently in use by USB.
ossMalloc( ) - Master USB memory allocation routine.
ossPartMalloc( ) - USB memory allocation.
ossOldMalloc( ) - Global memory allocation
ossCalloc( ) - Allocates memory initialized to zeros
ossFree( ) - Master USB memory free routine.
ossPartFree( ) - Frees globally allocated memory
ossOldFree( ) - Frees globally allocated memory
ossOldInstall( ) - Installs old method of USB malloc and free.
ossTime( ) - Returns relative system time in msec
ossInitialize( ) - Initializes ossLib
Implements functions defined by ossLib.h. See ossLib.h for a complete description of these functions.
ossStatus( ) - Returns OK or ERROR and sets errno based on status
STATUS ossStatus ( int status )
If status & 0xffff is not equal to zero, then sets errno to the indicated status and returns ERROR. Otherwise, does not set errno and returns OK.
OK or ERROR
ossShutdown( ) - Shuts down ossLib
STATUS ossShutdown (void)
This function should be called once at system shutdown if an only if the corresponding call to ossInitialize( ) was successful.
OK or ERROR
ossThreadCreate( ) - Spawns a new thread
STATUS ossThreadCreate ( THREAD_PROTOTYPE func, /* function to spawn as new thread */ pVOID param, /* Parameter to be passed to new thread */ UINT16 priority, /* OSS_PRIORITY_xxxx */ pCHAR name, /* thread name or NULL */ pTHREAD_HANDLE pThreadHandle /* Handle of newly spawned thread */ )
The ossThreadCreate( ) function creates a new thread which begins execution with the specified func. The param argument will be passed to func. The ossThreadCreate( ) function creates the new thread with a stack of a default size and with no security restrictions - that is, there are no restrictions on the use of the returned pThreadHandle by other threads. The newly created thread will execute in the same address space as the calling thread. priority specifies the thread's desired priority - in systems which implement thread priorities, as OSS_PRIORITY_xxxx.
OK or ERROR
S_ossLib_BAD_PARAMETER
S_ossLib_GENERAL_FAULT
ossThreadDestroy( ) - Attempts to destroy a thread
STATUS ossThreadDestroy ( THREAD_HANDLE threadHandle /* handle of thread to be destroyed */ )
This function attempts to destroy the thread specified by threadHandle.
Generally, this function should be called only after the given thread has terminated normally. Destroying a running thread may result in a failure to release resources allocated by the thread.
OK or ERROR
S_ossLib_GENERAL_FAULT
ossThreadSleep( ) - Voluntarily relinquishes the CPU
STATUS ossThreadSleep ( UINT32 msec /* Number of msec to sleep */ )
Threads may call ossThreadSleeph( ) to voluntarily release the CPU to another thread/process. If the msec argument is 0, then the thread will be reschuled for execution as soon as possible. If the msec argument is greater than 0, then the current thread will sleep for at least the number of milliseconds specified.
OK or ERROR
ossSemCreate( ) - Creates a new semaphore
STATUS ossSemCreate ( UINT32 maxCount, /* Max count allowed for semaphore */ UINT32 curCount, /* initial count for semaphore */ pSEM_HANDLE pSemHandle /* newly created semaphore handle */ )
This function creates a new semaphore and returns the handle of that semaphore in pSemHandle. The semaphore's initial count is set to curCount and has a maximum count as specified by maxCount.
OK or ERROR
S_ossLib_BAD_PARAMETER
S_ossLib_GENERAL_FAULT
ossSemDestroy( ) - Destroys a semaphore
STATUS ossSemDestroy ( SEM_HANDLE semHandle /* Handle of semaphore to destroy */ )
Destroys the semaphore semHandle created by ossSemCreate( ).
OK or ERROR
S_ossLib_GENERAL_FAULT
ossSemGive( ) - Signals a semaphore
STATUS ossSemGive ( SEM_HANDLE semHandle /* semaphore to signal */ )
This function signals the sepcified semaphore. A semaphore may have more than one outstanding signal, as specified by the maxCount parameter when the semaphore was created by ossSemCreate( ). While the semaphore is at its maximum count, additional calls to ossSemSignal for that semaphore have no effect.
OK or ERROR
S_ossLib_BAD_HANDLE
ossSemTake( ) - Attempts to take a semaphore
STATUS ossSemTake ( SEM_HANDLE semHandle, /* semaphore to take */ UINT32 blockFlag /* specifies blocking action */ )
ossSemTake( ) attempts to "take" the semaphore specified by semHandle. blockFlag specifies the blocking behavior. OSS_BLOCK blocks indefinitely waiting for the semaphore to be signalled. OSS_DONT_BLOCK does not block and returns an error if the semaphore is not in the signalled state. Other values of blockFlag are interpreted as a count of milliseconds to wait for the semaphore to enter the signalled state before declaring an error.
OK or ERROR
ossMutexCreate( ) - Creates a new mutex
STATUS ossMutexCreate ( pMUTEX_HANDLE pMutexHandle /* Handle of newly created mutex */ )
This function creates a new mutex and returns the handle of that mutex in pMutexHandle. The mutex is created in the "untaken" state.
OK or STATUS
S_ossLib_BAD_PARAMETER
S_ossLib_GENERAL_FAULT
ossMutexDestroy( ) - Destroys a mutex
STATUS ossMutexDestroy ( MUTEX_HANDLE mutexHandle /* Handle of mutex to destroy */ )
Destroys the mutex mutexHandle created by ossMutexCreate( ).
OK or ERROR
S_ossLib_GENERAL_FAULT
ossMutexTake( ) - Attempts to take a mutex
STATUS ossMutexTake ( MUTEX_HANDLE mutexHandle, /* Mutex to take */ UINT32 blockFlag /* specifies blocking action */ )
ossMutexTake( ) attempts to "take" the specified mutex. The attempt will succeed if the mutex is not owned by any other threads. If a thread attempts to take a mutex which it already owns, the attempt will succeed. blockFlag specifies the blocking behavior. OSS_BLOCK blocks indefinitely waiting for the mutex to be released. OSS_DONT_BLOCK does not block and returns an error if the mutex is not in the released state. Other values of blockFlag are interpreted as a count of milliseconds to wait for the mutex to be released before declaring an error.
OK or ERROR
ossMutexRelease( ) - Releases (gives) a mutex
STATUS ossMutexRelease ( MUTEX_HANDLE mutexHandle /* Mutex to be released */ )
Release the mutex specified by mutexHandle. This function will fail if the calling thread is not the owner of the mutex.
OK or ERROR
S_ossLib_BAD_HANDLE
ossPartSizeGet( ) - Retrieves the size of the USB memory partition.
UINT32 ossPartSizeGet (void)
Returns the size of the USB memory partition.
Size of partition.
ossPartSizeSet( ) - Sets the the initial size of the USB memory partition.
STATUS ossPartSizeSet ( UINT32 numBytes )
Sets the size of the USB memory partition. This must be called prior to the first call to ossMalloc. This will set the size that ossMalloc will use to do its allocation. Once ossMalloc has been called, the partition size has been already allocated. To add more memory to the USB partition, you must retrieve the USB partition ID and add more memory via the memPartLib routines.
OK or ERROR
ossPartIdGet( ) - Retrieves the partition ID of USB memory partition.
PART_ID ossPartIdGet (void)
Returns the partition ID of the USB memory partition.
The partition ID.
ossMemUsedGet( ) - Retrieves amount of memory currently in use by USB.
UINT32 ossMemUsedGet (void)
Returns the amount, in bytes, currently being used by USB.
Number of bytes of memory in use.
ossMalloc( ) - Master USB memory allocation routine.
void * ossMalloc ( UINT32 numBytes )
ossMalloc( ) calls the malloc routine installed in the global variable ossMallocFuncPtr. These default to ossPartMalloc( ), but can be changed by the user to their own defined malloc routine or to a non-partition method of malloc / free by calling ossOldInstall( ).
Pointer to allocated buffer, or NULL
ossPartMalloc( ) - USB memory allocation.
void * ossPartMalloc ( UINT32 numBytes /* Size of buffer to allocate */ )
ossPartMalloc( ) allocates cache-safe buffer of size numBytes out of the USB partition and returns a pointer to this buffer. The buffer is allocated from a local USB partition. The size of this partition is defaulted to 64k but can be modified to suit the users needs. This partition will dynamically grow based on additional need. Memory allocated by this function must be freed by calling ossFree( ).
Pointer to allocated buffer, or NULL
ossOldMalloc( ) - Global memory allocation
void * ossOldMalloc ( UINT32 numBytes /* Size of buffer to allocate */ )
ossOldMalloc( ) allocates a buffer of numBytes in length and returns a pointer to the allocated buffer. The buffer i allocated from a global pool which can be made visible to all processes or drivers in the system. Memory allocated by this function must be freed by calling ossFree( ).
Pointer to allocated buffer, or NULL
ossCalloc( ) - Allocates memory initialized to zeros
pVOID ossCalloc ( UINT32 numBytes /* size of buffer to allocate */ )
ossCalloc( ) uses ossMalloc( ) to allocate a block of memory and then initializes it to zeros. Memory allocated using this function should be freed using ossFree( ).
Pointer to allocated buffer, or NULL.
ossFree( ) - Master USB memory free routine.
void ossFree ( pVOID bfr )
ossFree( ) calls the free routine installed in the global variable ossFreeFuncPtr. This defaults to ossPartFree( ), but can be changed by the user to their own defined free routine or to a non-partition method of malloc / free by calling ossOldInstall( ).
N/A
ossPartFree( ) - Frees globally allocated memory
void ossPartFree ( pVOID bfr )
ossPartFree( ) frees memory allocated by ossMalloc( ).
N/A
ossOldFree( ) - Frees globally allocated memory
void ossOldFree ( void * bfr )
ossOldFree( ) frees memory allocated by ossMalloc( ).
N/A
ossOldInstall( ) - Installs old method of USB malloc and free.
void ossOldInstall (void)
Installs old method of USB malloc and free. This must be called before the call to usbdInitialize( ).
N/A
ossTime( ) - Returns relative system time in msec
UINT32 ossTime (void)
Returns a count of milliseconds relative to the time the system was started.
The time will wrap approximately every 49 days, so time calucations should always be based on the difference between two time values.
ossInitialize( ) - Initializes ossLib
STATUS ossInitialize (void)
This function should be called once at initialization in order to initialize the ossLib. Calls to this function may be nested. This permits multiple, indpendent libraries to use this library without need to coordinate the use of ossInitialize( ) and ossShutdown( ) across the libraries.
OK or ERROR