Subsystem Management Functions

Subsystem management functions extends the functions of T-Kernel itself by adding a user-defined function called "subsystem" to the kernel in order to implement middleware and others running on the T-Kernel. Some functions provided by T-Kernel/SM are also implemented by utilizing the subsystem management functions.

A subsystem consists of extended SVC handlers to execute user-defined system calls (called "extended SVCs"), a break function that performs the required processing when any exception occurs, an event handling function that performs the required processing when any event is raised from devices, etc., startup and cleanup functions that perform required processing at the start/exit of task for each resource group, and resource control blocks (Figure 15.)

Figure 15. T-Kernel Subsystems

The extended SVC handler directly accepts requests from applications and others. A break function, event processing function, startup function, and cleanup function are so-called callback type functions and accept requests from the kernel.

NoteAdditional Notes
 

Functions of T-Kernel Extension (T-Kernel Standard Extension) including the process management functions and the file management functions are also implemented by utilizing the subsystem management functions. Other examples of middleware for T-Kernel that are implemented by utilizing the subsystem management functions include TCP/IP manager, USB manager, and PC card manager.

Though subsystem management functions are equivalent to the extended SVC handlers and extended service calls provided in ITRON specification, they can be used to build complex and advanced middleware through not only the addition of just user-defined system calls but also through provision of resource management functions and exception processing functions to handle the exceptions, which are required for the added system calls.

Subsystem management functions manage resources by each resource group to which the task belongs. T-Kernel Extension (T-Kernel Standard Extension), a high level middleware of T-Kernel, uses T-Kernel resource group functions to realize a process. Because of the relationship described above, the resource management can be performed independently for each process in a subsystem by automatic execution of starup function or cleanup function defined in the subsystem upon creation (starting) or termination of a process. For example, if you want to automatically close a file that is not closed at the time of process termination, you can do so in the cleanup function included in the file management subsystem.

In addition to the subsystem management functions, T-Kernel also provides the device driver functions in order to extend itself. Both subsystems and device drivers are function modules independent from T-Kernel itself. They can be used by loading their corresponding binary programs into system space and then calling them from a task on T-Kernel. Both run at the protection level 0. While API is limited to using open/close and read/write type when calling a device driver, API for calling a subsystem can be defined without any restriction. Moreover, for the subsystem, there is a function that automatically manages a resource at the time of creating (starting) or terminating a resource group (process), for the device driver, there is no function to do so.

Subsystems are identified by subsystem IDs (ssid), more than one subsystem can be defined and used at the same time. One subsystem can be called and used from within another subsystem.

tk_def_ssy - Define Subsystem

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_def_ssy (ID ssid , CONST T_DSSY *pk_dssy );

Parameter

ID ssid Subsystem IDSubsystem ID
CONST T_DSSY* pk_dssy Packet to Define SubsystemSubsystem definition information

pk_dssy Detail:

ATR ssyatr Subsystem AttributesSubsystem attributes
PRI ssypri Subsystem PrioritySubsystem priority
FP svchdr Extended SVC Handler AddressExtended SVC handler address
FP breakfn Break Function AddressBreak function address
FP startupfn Startup Function AddressStartup function address
FP cleanupfn Cleanup Function AddressCleanup function address
FP eventfn Event Handling Function AddressEvent handling function address
INT resblksz Resource Control Block SizeResource control block size (in bytes)
(Other implementation-dependent parameters may be added beyond this point.)

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_ID Invalid ID number (ssid is invalid or cannot be used)
E_NOMEM Insufficient memory (memory for control block cannot be allocated)
E_RSATR Reserved attribute (ssyatr is invalid or cannot be used)
E_PAR Parameter error (pk_dssy is invalid or cannot be used)
E_OBJ ssid is already defined (when pk_dssyNULL)
E_NOEXS ssid is not defined (when pk_dssy = NULL)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

Defines subsystem specified in ssid.

One subsystem ID must be assigned to one subsystem without overlapping with other subsystems. The kernel does not have a function for assigning subsystem IDs automatically.

Subsystem IDs 1 to 9 are reserved for T-Kernel use. 10 to 255 are numbers used by middleware, etc. The maximum usable subsystem ID value is implementation-dependent and may be lower than 255 in some implementations.

ssyatr indicates system attributes in its lower bits and implementation-dependent attributes in its higher bits. The system attribute in ssyatr are not assigned in this version, and no system attributes are used.

ssypri indicates the subsystem priority. The startup function, cleanup function, and event handling function are called in order of priority. The calling order is undefined when these subsystems have the same priority. Subsystem priority 1 is the highest priority, with larger numbers indicating lower priorities. The range of priorities that can be specified is implementation-dependent, but it must be possible to assign at least priorities 1 to 16.

NULL can be specified in breakfn, startupfn, cleanupfn, and eventfn, in which case the corresponding function will not be called.

Specifying pk_dssy = NULL deletes a subsystem definition. The resource control block for the subsystem of ssid will also be deleted.

  • Resource control block

    The resource control block defines groups of resources and manages them by their attributes and other factors. Resource control block is allocated for each resource group. The block has its own memory area of the size specified in resblksz. If resblksz = 0 is specified, no resource control block is allocated; but a resource ID (see tk_cre_res) is assigned even in this case.

    Each task belongs to one resource group. When a task makes a request to a subsystem and resources are allocated to that task in the subsystem, the allocation information is stored in the resource control block. The subsystem decides what kinds of resource information to register in the resource control block and how they are to be registered.

    The kernel is not responsible for the content of the resource control block; it can be used freely by the subsystem. The size specified in resblksz should, however, be as small as possible. If a larger memory block is needed, the subsystem should allocate that memory on its own and register its address in the resource control block.

    A resource control block is located in resident memory of shared (system) space.

  • Extended SVC handler

    An extended SVC handler accepts requests from applications and other programs as an application programming interface (API) for a subsystem. It can be called in the same way as an ordinary system call, and is normally invoked using a trap instruction or the like.

    The format of an extended SVC handler is as follows.

    INT svchdr( void *pk_para, FN fncd )
    {
            /*
                    branching by fncd
            */
    
            return retcode; /* exit extended SVC handler */
    }

    fncd is a function code. The lower 8 bits of the instruction code are the subsystem ID. The remaining higher bits can be used in any way by the subsystem. Ordinarily they are used as a function code inside the subsystem. A function code must be a positive value, so the most significant bit is always 0.

    pk_para points to a packet of parameters passed to this system call. The packet format can be decided by the subsystem. Generally a format like the stack passed to a C language function is used, which in many cases is the same format as a C language structure.

    The return code passed from an extended SVC handler is passed to the caller transparently as the function return code. As a rule, negative values are error codes and 0 or positive values are the return code for normal completion. If an extended SVC call fails for some reason, the error code (negative value) set by T-Kernel is returned to the caller without invoking the extended SVC handler, so it is best to avoid confusion with these values.

    The format by which an extended SVC is called is dependent on the kernel implementation. As a subsystem API, however, it must be specified in a C language function format independent of the kernel implementation. The subsystem must provide an interface library for converting from the C language function format to the kernel-dependent extended SVC calling format.

    An extended SVC handler runs as a quasi-task portion.

    It can be called from a task-independent portion, and in this case the extended SVC handler also runs as a task-independent portion.

  • Break function

    A break function is a function called when a task exception is raised for a task while an extended SVC handler is executing.

    When a break function is called, the processing by the extended SVC handler running at the time the task exception was raised must be stopped promptly and control must be returned from the extended SVC handler to its caller. The role of a break function is to abort the processing of the currently running extended SVC handler.

    The format of a break function is as follows.

    void breakfn( ID tskid )
    {
            /*
                    stop the running extended SVC handler
            */
    }

    tskid is the ID of the task in which the task exception was raised.

    A break function is called when a task exception is raised by tk_ras_tex. If extended SVC handler calls are nested, then when the nesting level of the extended SVC handler is decreased by the return from the latest extended SVC handler, the break function corresponding to the former extended SVC handler to which the control will be returned next, is called.

    A break function is called only once for one extended SVC handler per one task exception.

    If another nested extended SVC call is made while a task exception is raised, no break function is called for the called extended SVC handler.

    A break function runs as a quasi-task portion. Its requesting task is identified as follows: If a break function is called by tk_ras_tex, it runs as a quasi-task portion of the task that issued tk_ras_tex. On the other hand, when the nesting level of extended SVC handler is decreased, the break function runs as a quasi-task portion of the task that raised the task exception (the task running the extended SVC handler). This means that the task executing the break function may be different from the task executing the extended SVC handler. In such a case, the break function and extended SVC handler run concurrently as controlled by task scheduling.

    It is thus conceivable that the extended SVC handler will return to its caller before the break function finished executing, but in that case the extended SVC handler waits at the point right before returning, until the break function completes. How this waiting state maps to the task state transitions is implementation-dependent, but preferably it should remain in READY state (a READY state that does not go to RUNNING state). The precedence of a task may change while it is waiting for a break function to complete, but how task precedence is treated is implementation-dependent.

    Similarly, an extended SVC handler cannot call an extended SVC until break function execution completes.

    In other words, during the time from the raising of a task interrupt until the break function completes, the affected task must stay in the extended SVC handler that was executing at the time of the task exception.

    In the case where the requesting task of the break function differs from that of the extended SVC handler, that is, where the break function and the extended SVC handler run in different task contexts, the task priority of the break function is raised to the same as that of the extended SVC handler only while the break handler is executing if the former is lower than the latter. On the other hand, if the break function task priority is the same as or higher than that of the extended SVC handler, the priority does not change. The priority that gets changed is the current priority; the base priority stays the same.

    The change in priority occurs only immediately before entry into the break function; any changes after that of the extended SVC handler task priority are not followed by further changes in priority of the break function task. In no case does a change in the break function priority while a break function is running results in a priority change in the extended SVC handler task. At the same time, there is no restriction on priority changes due to a running break function.

    When the break function completes, the current priority of its task reverts to base priority. If a mutex was locked, however, the priority reverts to that as adjusted by the mutex. (In other words, the ability is provided to adjust the current priority at the entry and exit of the break function only; other than that, the priority is the same as when an ordinary task is running.)

  • Startup function

    A startup function is called by issuing the tk_sta_ssy system call.

    It performs resource control block initialization processing.

    The format of a startup function is as follows.

    void startupfn( ID resid, INT info )
    {
            /*
                    resource control block initialization processing
            */
    }

    resid is the ID of the resource group to be initialized, and info is a parameter that can be used in any way. Both are passed specified in tk_sta_ssy.

    Even if initialization of the resource control block fails for some reason, the startup function must be terminated normally. If the resource control block could not be initialized, the extended SVC handler returns error code when the API is called and cannot be executed normally, as a result of unsuccessful initialization of the resource control block.

    A startup function runs as a quasi-task portion of the task that issued tk_sta_ssy.

  • Cleanup function

    A cleanup function is called by issuing the tk_cln_ssy system call.

    It performs resource release processing.

    The format of a cleanup function is as follows.

    void cleanupfn( ID resid, INT info )
    {
            /*
                    resource release processing
            */
    }

    resid is the ID of the resource group to be released, while info is a parameter that can be used freely. Both are parameters specified in tk_cln_ssy.

    Even if releasing fails for some reason, the cleanup function must be terminated normally. The error handling method, such as logging of errors, are left to the subsystem implementing vendor to decide.

    After the cleanup function completes its processing, the resource control block is automatically cleared to 0. If no cleanup function was defined (cleanupfn = NULL), the tk_cln_ssy system call clears the resource control block to 0.

    A cleanup function runs as a quasi-task portion of the task that issued tk_cln_ssy.

  • Event handling function

    An event handling function is called by issuing the tk_evt_ssy system call.

    It processes various requests made to a subsystem.

    Note that it has to process all requests for all subsystems. If processing is not required, it can simply return E_OK without performing any operation.

    The format of an event handling function is as follows.

    ER eventfn( INT evttyp, ID resid, INT info )
    {
            /*
                    event processing
            */
    
            return ercd;
    }

    evttyp indicates the request type, resid gives the ID of the resource group, and info is a parameter that can be used freely. All these parameters are passed to tk_evt_ssy. If the system call is not invoked for any particular resource group, resid can be set to 0.

    If processing completes normally, E_OK is passed in the return code; otherwise an error code (negative value) is returned.

    The following event types evttyp are defined. For more details, see the Section called Device Management Functions in the Chapter called T-Kernel/SM Functions.

    #define TSEVT_SUSPEND_BEGIN     1       /* before suspending device */
    #define TSEVT_SUSPEND_DONE      2       /* after suspending device */
    #define TSEVT_RESUME_BEGIN      3       /* before resuming device */
    #define TSEVT_RESUME_DONE       4       /* after resuming device */
    #define TSEVT_DEVICE_REGIST     5       /* device registration notice */
    #define TSEVT_DEVICE_DELETE     6       /* device deletion notice */

    An event handling function runs as a quasi-task portion of the task that issued tk_evt_ssy.

Additional Notes

Extended SVC handlers as well as break functions, startup functions, cleanup functions and event handling functions all have the equivalent of the TA_HLNG attribute only. There is no means of specifying the TA_ASM attribute.

Prior to initialization of a resource control block by the startup function, and after resource release by the cleanup function, the behavior if an extended SVC is called by a task belonging to that resource group is dependent on the subsystem implementation. The kernel does not make any attempt to prevent this kind of call. Basically it is necessary to avoid calling an extended SVC before calling the startup function and after calling the cleanup function.

There may be cases where, for some reason or other, the break function, cleanup function or event handling function is called without first calling the startup function. These functions must execute normally even in such a case. A resource control block is cleared to 0 when it is first created and when cleanup processing is executed by tk_cln_ssy. Accordingly, even if it was not initialized properly by a startup function, the resource control block can still be assumed to have been cleared to 0.

The task space in the extended SVC handler is the same as that of the caller. Therefore, it is not necessary to switch the task space even when accessing the buffer passed by the caller. However, the extended SVC handler runs at protection level 0 (privileged mode), which makes it possible to access the memory that the caller task is not permitted to access. For this reason, in the extended SVC handler, the access permission check should be performed as necessary, using ChkSpaceR(), ChkSpaceRW(), and so on.

It is possible to issue a system call that enters WAITING state in the extended SVC handler, but in that case the program must be designed so that it can be stopped by calling a break function. The specific processing flow is as follows: If tk_ras_tex is issued for the caller task while an extended SVC handler is executing, it is necessary to stop the running extended SVC handler as soon as possible and return a stop error to the caller task. For this purpose the break function is used. In order to stop the running extended SVC handler immediately, the break function must forcibly release the WAITING state, even if the system call is in WAITING state during processing the extended SVC handler. For this purpose, the tk_dis_wai system call is generally used. tk_dis_wai can prevent the system call from entering WAITING state until the control returns from the extended SVC handler to the caller task, but the implementor should also make it possible to stop the program of the extended SVC handler by calling a break function. For example, leaving from WAITING state with the error code E_DISWAI can mean that the execution is stopped by a break function. So it is best to stop the extended SVC handler immediately and return a stop error to the caller task, without continuing to execute the subsequent processing.

An extended SVC handler may be called concurrently by multiple tasks. If the tasks share same resources, the mutual exclusion control must be performed in the extended SVC handler.

tk_sta_ssy - Call Startup Function

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_sta_ssy (ID ssid , ID resid , INT info );

Parameter

ID ssid Subsystem IDSubsystem ID
ID resid Resource IDResource ID
INT info InformationAny parameter

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_ID Invalid ID number (ssid or resid is invalid or cannot be used)
E_NOEXS Object does not exist (the subsystem specified in ssid is not defined)
E_CTX Context error (issued from task-independent portion, or in dispatch disabled state)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

Calls the startup function of the subsystem specified in ssid.

Specifying ssid = 0 makes the system call applied to all currently defined subsystems. In this case the startup function of each subsystem is called in descending order of priority.

The calling order is undefined when these subsystems have the same priority.

If there are dependency relationships among different subsystems, the subsystem priority must therefore be set with those relationships in mind. If, for example, subsystem B uses functions in subsystem A, then the priority of subsystem A must be set higher than that of subsystem B.

If this system call is issued for a subsystem with no startup function defined, the function is simply not called; no error results.

If a task exception is raised for the task that called tk_sta_ssy during startup function execution execution, the task exception is held until the startup function completes its processing.

Additional Notes

T-Kernel Extension (T-Kernel Standard Extension), a higher level middleware of T-Kernel, uses tk_sta_ssy and tk_cln_ssy to perform the startup processing during process creation (startup) and the cleanup processing during process termination, respectively. Specifically, during the processing of process creation (startup) in T-Kernel Extension, tk_sta_ssy is issued specifying ssid = 0 to perform the startup processing for the newly started process. During the processing of process termination in T-Kernel Extension, tk_cln_ssy is issued specifying ssid = 0 to perform the cleanup processing for the process to be terminated. For example, when the file management subsystem performs the cleanup processing for terminating a process, the subsystem can use this function to automatically close the file opened by that process.

If multiple subsystems are defined, the startup/cleanup function of each subsystem is executed in the order determined by subsystem priority, which is reversed between the startup processing and the cleanup processing.

For example, in the case where Subsystem A is used to implement another Subsystem B, the priority of Subsystem A should be higher than that of Subsystem B. This makes the startup processing of Subsystem A being executed before Subsystem B for the process to be newly started. Thus, the function (extended SVC handler) of Subsystem A can be called during the startup processing of Subsystem B. On the other hand, the cleanup processing of Subsystem B is executed before Subsystem A for the process to be terminated. Thus, the function (extended SVC handler) of Subsystem A can be called during the cleanup processing of Subsystem B (see Figure 16).

Figure 16. Dependency and Priority of Subsystems

The startup functions of all the subsystems are always executed each time a new process is created (started). The started process does not necessarily use all of the subsystem functions, or it may never call them. Considering that all of the startup functions of subsystems are executed when a process (including one unrelated to the subsystems) is created (started), the overhead due to startup functions should be minimized. To do this, the startup function should only perform the bare minimum of processing, and a complicated processing, if necessary, should be deferred without being executed in the startup function until the subsystem is actually used, for example when the extended SVC handler is called from the process for the first time.

tk_cln_ssy - Call Cleanup Function

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_cln_ssy (ID ssid , ID resid , INT info );

Parameter

ID ssid Subsystem IDSubsystem ID
ID resid Resource IDResource ID
INT info InformationAny parameter

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_ID Invalid ID number (ssid or resid is invalid or cannot be used)
E_NOEXS Object does not exist (the subsystem specified in ssid is not defined)
E_CTX Context error (issued from task-independent portion, or in dispatch disabled state)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

Calls the cleanup function of the subsystem specified in ssid.

Specifying ssid = 0 makes the system call applied to all currently defined subsystems. In this case the cleanup function of each subsystem is called in ascending order of priority.

The calling order is undefined when these subsystems have the same priority.

If there are dependency relationships among different subsystems, the subsystem priority must therefore be set with those relationships in mind. If, for example, subsystem B uses functions in subsystem A, then the priority of subsystem A must be set higher than that of subsystem B.

If this system call is issued for a subsystem with no cleanup function defined, the function is simply not called; no error results.

If a task exception is raised for the task that called tk_cln_ssy during cleanup function execution, the task exception is held until the cleanup function completes its processing.

tk_evt_ssy - Call Event Function

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_evt_ssy (ID ssid , INT evttyp , ID resid , INT info );

Parameter

ID ssid Subsystem IDSubsystem ID
INT evttyp Event TypeEvent request type
ID resid Resource IDResource ID
INT info InformationAny parameter

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_ID Invalid ID number (ssid or resid is invalid or cannot be used)
E_NOEXS Object does not exist (the subsystem specified in ssid is not defined)
E_CTX Context error (issued from task-independent portion, or in dispatch disabled state)
OtherError code returned by the event handling function

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

Calls the event handling function of the subsystem specified in ssid.

Specifying ssid = 0 makes the system call applied to all currently defined subsystems. In this case the event handling function of each subsystem is called in sequence.

When evttyp is an odd number:

Calls subsystems in descending order of priority.

When evttyp is an even number:

Calls subsystems in ascending order of priority.

The calling order is undefined wheren these subsystems have the same priority.

If this system call is issued for a subsystem with no event handling function defined, the function is simply not called; no error results.

If this system call is not invoked for any particular resource group, set resid to 0.

If the event handling function returns an error, the error code is passed transparently in the system call return code. When ssid = 0 and an event handler returns an error, the event handling functions of all other subsystems continue to be called. In the system call return code, only one error code is returned even if more than one event handling function returned an error. It is not possible to know which subsystem's event handling function returned the error.

If a task exception is raised for the task that called tk_evt_ssy, during the execution of event handling function, the task exception is held until the event handling function completes its processing.

Additional Notes

An example of using an event handling function is to perform the suspend/resume processing for the power management functions. Specifically, when the system enters the power-off state (device suspended state) due to power failure or other reason, it notifies each subsystem of its transition to suspended state. Then the event handling function of each subsystem is called to perform the appropriate processing for it. In T-Kernel/SM, tk_evt_ssy is executed for this purpose during the processing of tk_sus_dev. The event handling function of each subsystem performs any necessary operations before going to suspended state, such as saving the data. On the other hand, when the system returns (resumes) from the suspended state due to power on or other reason, it notifies each subsystem of its return from suspended state. Then the event handling function of each subsystem is called again to perform the appropriate processing for it. For more details, see the description of tk_sus_dev.

For another example, when a new device is registered by tk_def_dev, the system notifies each subsystem of the registration, and the event handling function of each subsystem is called to perform the appropriate processing for it. In T-Kernel/SM, tk_evt_ssy is executed for this purpose during the processing of tk_def_dev.

tk_ref_ssy - Reference Subsystem Status

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_ref_ssy (ID ssid , T_RSSY *pk_rssy );

Parameter

ID ssid Subsystem IDSubsystem ID
T_RSSY* pk_rssy Packet to Return Subsystem StatusPointer to the area to return the subsystem definition information

Return Parameter

ER ercd Error CodeError code

pk_rssy Detail:

PRI ssypri Subsystem PrioritySubsystem priority
INT resblksz Resource Control Block SizeResource control block size (in bytes)
(Other implementation-dependent parameters may be added beyond this point.)

Error Code

E_OK Normal completion
E_ID Invalid ID number (ssid is invalid or cannot be used)
E_NOEXS Object does not exist (the subsystem specified in ssid is not defined)
E_PAR Parameter error (invalid pk_rssy)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

References information about the subsystem specified in ssid.

ssypri returns the subsystem priority specified in tk_def_ssy.

resblksz returns the size of the resource control block specified in tk_def_ssy.

If the subsystem specified in ssid is not defined, E_NOEXS is returned.

tk_cre_res - Create Resource Group

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_cre_res ( void );

Return Parameter

ID resid Resource IDResource ID
orError CodeError code

Error Code

E_LIMIT Number of resource groups exceeds the system limit
E_NOMEM Insufficient memory (memory for control block cannot be allocated)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

Creates a new resource group, assigning to it a resource control block and resource ID.

Resource IDs are assigned in common for the entire system. A separate resource control block is created for each subsystem (see the description of Figure 17).

Figure 17. Subsystems and Resource Groups

A new subsystem can be defined when a resource group is already created. Even in such a case, it is necessary to create a resource control block of an already existing resource group for the newly registered subsystem. In other words, there may be cases where resource control block must be created by tk_def_ssy.

For example, if a new subsystem ID is defined in a situation like that shown in Figure 17, resource control blocks with resource IDs #1, #2, and #3 must automatically be created for the subsystem.

Additional Notes

A Resource ID is in some cases used also as a logical space ID (lsid). Resource IDs should therefore be assigned values that can be used directly as logical space IDs or that can easily be converted for use as logical space IDs.

A system resource group always exists as a special resource group. One system resource group always exists, moreover, from the time the system boots, without waiting for creation by tk_cre_res. The system resource group cannot be deleted. Other than the point that it always exists, a system resource group is no different from other resource groups.

Resource control block creation might be implemented in either of the following ways.

  • (A) At the time of subsystem definition (tk_def_ssy), create as many resource control blocks as the maximum number of resource groups, and use tk_cre_res simply to assign them.

  • (B) Use tk_cre_res to create as many resource control blocks as there are subsystems and assign them.

Since the specification requires clearing a resource control block to 0 when it is initially created, the timing of this clearing to 0 differs between methods (A) and (B). This difference should not have much of an effect; but since method (A) will have fewer cases of clearing to 0, subsystems must be implemented assuming (A). Method (A) is also recommended for the kernel implementation.

T-Kernel Extension (T-Kernel Standard Extension), a higher level middleware of T-Kernel, uses the resource group function of T-Kernel to achieve various functions of process, where one process corresponds to one resource group. For this reason, when creating (starting) a process, it is necessary to allocate a resource control block for it by executing tk_cre_res.

Using the resource control function, each subsystem can allocate an independent resource to each process (that is, to each resource group), or can automatically release the allocated resource when the process is terminated. For example, a file management subsystem often assigns an identifier called "file descriptor" to a file each time a process opens it, and usually uses that file descriptor for subsequent file manipulations. In this case, various management information identified by the file descriptor for file manipulation is the resource. Placing this resource in the resource control block for the file management subsystem allows the information for file manipulation to be managed independently for each process (resource group).

Generally, for subsystems that realize functions which should be controlled independently for each process, it is effective to use the resource control block to manage the information of each process independently. It is also possible to use the startup function to prepare the subsystem side or initialize the resource control block for a newly created (started) process, or to use the cleanup function to automatically release the resources when the process is terminated. On the other hand, for subsystems that realize functions which is not directly related to a process (such as functions shared between processes, or functions for the entire system), functions related to the resource control block, resources, and resource groups have less chance to be used.

When a new process is created (started), the resource control block for each subsystem is allocated in the resident memory area of the system shared space, regardless of whether the process actually uses the subsystem or not. That means that some system shared memory is consumed. To reduce the overhead for the entire system, it is best to minimize the size of the resource control block.

Suppose, for example, there is a subsystem that needs 1 MB of independent working memory for each process. As the working memory is required for each process, you might choose to use a part of the resource control block for the working memory, but the amount is too large for the resource control block. If the resource control block size is set to 1 MB, that amount of space is unconditionally allocated each time when a new process is created (started), which consumes too much resident memory of the system shared space. Especially, if a new process never uses the function of this subsystem, too much memory is wasted.

In such case, it is best to defer the allocation of the working memory used by subsystem until it is actually required. To do so, for example, include in the resource control block only the flag indicating whether the working memory space has been allocated or not, and the address of the working memory space. Then check the flag when the process uses the subsystem function (calls the extended SVC handler), and allocate the working memory space only if it is not yet allocated. This solution can eliminate the waste of memory space caused by allocating the large resource control block to a process that does not call the subsystem.

tk_del_res - Delete Resource Group

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_del_res (ID resid );

Parameter

ID resid Resource IDResource ID

Return Parameter

ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_ID Invalid ID number (resid is invalid or cannot be used)
E_NOEXS Object does not exist (the resource specified in resid does not exist)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

Deletes the resource control blocks of the resource group specified in resid, and releases the resource ID.

The resource control blocks of all subsystems are deleted.

Additional Notes

Resources are deleted even if there are still tasks belonging to a resource to be deleted. In principle, resource deletion must be performed after exit and deletion of all tasks belonging to the resources. The behavior is not guaranteed if a resource is deleted while a task belonging to that resource remains and is calling a subsystem (extended SVC). Likewise, the behavior is not guaranteed if a task belonging to a deleted resource calls a subsystem (extended SVC).

The timing for actual resource control block deletion is implementation-dependent (See tk_cre_res).

The system resource group cannot be deleted (error code E_ID is returned).

tk_get_res - Get Resource Management Block

C Language Interface

#include <tk/tkernel.h>

ER ercd = tk_get_res (ID resid , ID ssid , void **p_resblk );

Parameter

ID resid Resource IDResource ID
ID ssid Subsystem IDSubsystem ID
void** p_resblk Resource Control BlockPointer to the area to return the return parameter resblk

Return Parameter

void* resblk Resource Control BlockResource control block
ER ercd Error CodeError code

Error Code

E_OK Normal completion
E_ID Invalid ID number (resid or ssid is invalid or cannot be used)
E_NOEXS Object does not exist (the resource specified in resid or ssid does not exist)
E_PAR Parameter error (invalid p_resblk)

Valid Context

Task portionQuasi-task portionTask-independent portion
YESYESNO

Description

Gets the address of the resource control block of resource group resid for subsystem ssid.

Additional Notes

E_OK might be returned even if this system call is issued for a deleted resource ID. Whether or not error (E_NOEXS) is returned in this case is implementation-dependent.