UOS API, the Application Side

Since UCL is a textual user interface, it will need to let the user know when it is ready to accept input. This is called "prompting" the user. In an example of nouning verbs, the textual indicator used to prompt the user is called "a prompt". UCL allows the user to customize his own prompt. This is done by defining the symbol "$ucl_prompt". Whatever value that symbol has is used as the prompt. If the symbol isn't defined (which it isn't by default), or it is empty, UCL will display it's default prompt - a dollar sign ($) and space. Thus, the first order of business when displaying a prompt will be to obtain the contents of $ucl_prompt.

procedure Show_Prompt ;

var S : Ansistring ;

begin
    S := LIB_Get_Symbol( '$ucl_prompt' ) ;
    if( S = '' ) then
    begin
        S := '$ ' ;
    end ;
    LIB_Put_Output( S ) ;
end ;

Let's look at the LIB_Get_Symbol call now. Because of the ring security model used by UOS, transferring data between the executive and application programs is not as straight-forward as passing parameters to normal functions. Exactly how much data can be passed to an inner ring is dependent upon the CPU architecture. In the case of MSDOS, for instance, the parameters were stored in registers. To provide compatibility with the widest range of potential hardware platforms, In UOS, the parameters are stored in a structure in memory, and a pointer to this structure is what is passed to the executive. The result of the call is usually stored back into that structure as well. Starlet contains the code to call into the executive which is suitable for low-level code, such as assembly language. It also includes a set of wrapper functions that translate normal functions into API calls, and return data in a way that is "natural" to most high-level programming languages.

The structure, whose address is passed to the executive, has a standard layout section followed by a section that is dependent upon the specific call. The standard layout is as follows:

type TSystem_Request = packed record
                           Subsystem : longint ; // Executive component
                           Request : longint ; // Request
                           Length : word ; // Length of call-specific following data, in bytes
                           Status : int64 ; // Ignored on call, result status on return
                           Flags : int64 ; // Flags (depends upon call)
                           // Call-specific details follow
                       end ;
     PSystem_Request = ^TSystem_Request ;

const UOS_Subsystem_MMC = 1 ;
const UOS_Subsystem_FIP = 2 ;
const UOS_Subsystem_USC = 3 ;
const UOS_Subsystem_SSC = 4 ;
const UOS_Subsystem_Kernel = 5 ;

Although the TSystem_Request structure is sufficient for passing fixed-size data, such as integers, it is less useful when passing arbitrary-length textual (string) data. Thus, the call-specific code for LIB_Get_Symbol includes additional structures which are used to pass string data to the Kernel (and back). The TSRB structure is used to transfer string data.

type TSRB = packed record
                Buffer : int64 ; // Pointer to string Buffer
                Length : int64 ; // Length of string buffer
                Flags : longint ; // Reserved for future use
            end ;

TSRB doesn't contain the string data. Rather it has a pointer to the data, and an integer value indicating the length. This provides the maximum flexibility as it allows any size chunk of data to be transferred to or from the executive. Obviously, Buffer must point to memory that is allocated to the application, and the length must indicate the actual length of the data. If either is incorrect, the result is likely that the application terminates with an error. This defines how we pass data to the executive, but passing data back is different. Inner rings can access the data of more outer rings so they can read the buffer pointed to by the TSRB structure. However, outer rings (such as where the applications run) cannot access the memory of more inner rings. Thus, there is no way for the application to directly retrieve data from the executive. Instead, we must follow a three-step process. First, we must request a size for the data that the executive will return to us. Second, we can allocate a buffer to hold that data. Third, we obtain the data by asking the executive to fill our buffer. Of course, we could allocate a really big buffer and hope that it was large enough for the data to fit, but there are two problems with this approach: 1) the data might exceed the size of the buffer resulting in truncated data, and 2) we may waste a large amount of memory for data which is usually smaller in size. Thus, we will always use the three-step method in Starlet.

Because LIB_Get_Symbol obtains a symbol's contents, which is of arbitrary length, the function needs to follow these three steps. The structure that we pass to UOS involves two strings: the name of the symbol, and where to return that symbol's contents. So, the structure we pass contains two TSRB substructures, plus an integer value (for the table), in addition to the fixed portion of TSystem_Request. We call this structure TString2I1_Request, since it is a system request that takes two strings and 1 integer.

type TString2I1_Request = packed record
                              Request : TSystem_Request ;
                              String1 : TSRB ; // Parameter
                              String2 : TSRB ; // Result
                              Integer1 : longint ;
                         end ;
     PString2I1_Request = ^TString2I1_Request ;

One more complication exists that is a consequence of the UOS simulator itself. The simulator sets aside a large buffer of memory that acts as the system memory for UOS. By use of our memory management scheme, all memory allocations for strings and heap usage come from that memory. However, anything allocated in the stack or data segments might be allocated outside of this memory. If UOS tries to access this memory, it might see it as an invalid address. Perhaps in the future we can discuss the gory details of the simulator and the environment it creates for UOS to run within, but for now just take it for granted. Thus, we must make sure to allocate any data (including the request structure itself) on the heap. Normally, we wouldn't code anything specifically for a given platform - especially the simulator. However, this code will work on any/all platforms. Further, it is possible that using stack data on some platforms may require different access mechanisms.

function LIB_Get_Symbol( const Name : string ; Table : longint = 0 ) : string ;

var SysRequest : PString2I1_Request ;

begin
    // Setup...
    Result := '' ;
    getmem( SysRequest, sizeof( SysRequest^ ) ) ;
    fillchar( SysRequest^, sizeof( SysRequest^ ), 0 ) ;
    SysRequest.Request.Subsystem := UOS_Subsystem_SSC ;
    SysRequest.Request.Request := UOS_SSC_Get_Symbol ;
    SysRequest.Request.Length := sizeof( SysRequest^ ) - sizeof( TSystem_Request ) ;

    Set_String( Name, SysRequest.String1 ) ;
    SysRequest.Integer1 := Table ;

procedure Set_String( const Name : string ; var SRB : TSRB ) ;

begin
    SRB.Buffer := int64( PChar( Name ) ) ; // Symbol name
    SRB.Length := length( Name ) ;
end ;

Next we make the call to UOS:

    // Get size of symbol...
    Call_To_Ring0( integer( SysRequest ) ) ;
    if( Status.Status <> UE_Success ) then // Failed
    begin
        exit ;
    end ;

    // Receive value...
    setlength( Result, SysRequest.String2.Length ) ;
    if( SysRequest.String2.Length > 0 ) then
    begin
        SysRequest.String2.Buffer := int64( PChar( Result ) ) ;
        Call_To_Ring0( integer( SysRequest ) ) ;
        if( Status.Status <> UE_Success ) then // Failed
        begin
            Result := '' ;
            exit ;
        end ;
    end ;
end ; // LIB_Get_Symbol

The Call_to_Ring0 function is how Starlet jumps into the Executive, which runs in ring 0. The actual mechanism that is used for this is dependent upon the platform that UOS is running on and so we won't cover that here. We are guaranteed, however, that the kernel will return to this point when it is done, regardless of the architecture.

In the next article, we will look at how the Executive handles calls that are made via Call_to_Ring0.

Copyright © 2018 by Alan Conroy. This article may be copied in whole or in part as long as this copyright is included.