www.beck-ipc.com

@CHIP-RTOS C Library - RTOS API


RTX_Count_Resources

This diagnostic routine reads out the number of RTX resources available and optionally obtains detailed data about the resources that are in use.

int RTX_Count_Resources (RTX_COUNTS far *counts,
                         void       far *details,
                         unsigned int     list_size,
                         unsigned int    filter );

Parameters

counts

Output parameter:  Pointer to an RTX_COUNTS data structure that will be filled by this API.

details

Optional Output parameter:   Pointer to a buffer which will receive objects which can be referenced with the RTX_DETAILS union of structure pointers.   This API will report various details for each RTX object to this buffer.   This parameter can be set to NULL if no detailed RTX object data is desired.

list_size

Number of bytes in buffer at details .   If either this value is zero or details is NULL, then no RTX_DETAILS reporting is done.

filter

Optional output listing filter.   This bit field selects which type RTX objects are listed in detailed report at details .   Set this to zero to report all object types.

Return Value

-1:   Pointer counts was not valid.

>= 0:   Number of RTX_DETAILS structures output to array at details .   If this count is lower than the nReport_Cnt member of the RTX_COUNTS output to counts then the report was not complete due to insufficient buffer space (list_size less than nReport_Bytes member of RTX_COUNTS ).

Comments

The primary purpose for this API is to allow the user to determine the number of RTX resources that are available.   For this limited purpose, only the RTX_COUNTS data structure is required at the location referenced by the counts parameter.   The details parameter can be set to NULL or list_size parameter set to zero to indicate that no RTX_DETAILS reporting is desired.

When more detailed information about the various RTX objects in use is desired, an array of RTX_DETAILS unions can be provided by the caller at location specified by the details pointer.   The number of bytes space available in this buffer is specified in the list_size argument.   This API will then report details for as many of the selected RTX objects as will fit into this buffer space.

The report filter parameter allows you to focus the detailed reporting on particular types of RTX objects.   This can simplify your memory management problem by reducing the size of the RTX_DETAILS array at details required to report all the objects of the type you are interested in.   Bits set to one in this bit field inhibit the reporting of the RTX object type associated with that bit.   The following filter masks are defined in RTXAPI.H header file for this purpose:

    RTX_FILT_SEM - Enables semaphore detail reporting

    RTX_FILT_TIMER - Enables timer detail reporting

    RTX_FILT_EVENT_GROUP - Enables Event Group detail reporting

    RTX_FILT_MSGXCHG - Enables Message Exchange detail reporting

    RTX_FILT_TASK - Enables task detail reporting

Each of these mask has all bits set except for one.   These masks can be combined with the bit wise AND operation to report more than one object type.   For example:

    RTX_FILT_SEM & RTX_FILT_EVENT_GROUP

for the filter argument would report both semaphore and Event Group objects.

One possible strategy for allocating the details buffer memory would be to first call this API with list_size set to zero only to discover how large a buffer will be required to collect the desired detailed information.   The number of buffer bytes required is reported by the API in the nReport_Bytes member of the RTX_COUNTS data structure.   This reported count is influenced by what ever reporting filter you had specified.

Inside this API, the RTX data is collected with the task switching locked.   Interrupts are enabled after inhibiting task switching.   The interrupt mask is restored to the state on entry prior to re-enabling the task switching on return.   Nevertheless, a task switch can occur at the moment task switching is re-enabled here, thereby defeating any interrupt mask set by the caller.

See Also

RTOS API

This library function invokes a RTOS software interrupt. Refer to this RTOS API function's documentation for more details.

Related Topics

RTX API   Overview

Supported since or modified in @CHIP-RTOS version

    SC12SC13SC11SC1x3SC2x
    V1.20V1.20V1.20V0.91V1.00

Supported by @CHIP-RTOS C Library since version

    CLIB
    V2.02

This API List
List of C Libraries
@CHIP-RTOS Main Index


End of document