CONTENTS

  Title Page

  Copyright Page

  Preface

  1      Introduction

  1.1     VAXELN Kernel

  1.2     Jobs and Processes

  1.3     Kernel Routine Dispatching

  1.4     Memory Management

  1.5     Kernel Objects and Object Management
    1.5.1      Area Objects
    1.5.2      Device Objects
    1.5.3      Event Objects
    1.5.4      Message Objects
    1.5.5      Name Objects
    1.5.6      Port Objects
    1.5.7      Process Objects
    1.5.8      Semaphore Objects
    1.5.9      Kernel Object Implementation
      1.5.9.1      Implementing Port Objects
    1.5.10     Optimized Objects
      1.5.10.1     AREA_LOCK_VARIABLE
      1.5.10.2     MUTEX

  1.6     Job and Process Scheduling

  1.7     Job and Process Synchronization

  1.8     Concurrent Execution
    1.8.1      Multitasking
    1.8.2      Multiprogramming
    1.8.3      Multiprocessing

  1.9     Device Handling

  1.10    Interjob Communication

  1.11    Condition Handling

  1.12    Error and Event Reporting

  2      Jobs and Processes

  2.1     Activating and Terminating a Job and Master Process

  2.2     Activating and Terminating a Subprocess

  2.3     Scheduling Jobs and Processes
    2.3.1      Process States
    2.3.2      Assigning Priorities
    2.3.3      Scheduling in Multiprocessing Configurations
    2.3.4      Scheduling Initialization Programs at System Start-Up

  2.4     Loading Program Images

  2.5     Setting a Job's Processor Eligibility

  2.6     Kernel Services for Processes and Jobs

  3      Memory Management

  3.1     Mapping a VAXELN System into S0 Address Space

  3.2     Mapping a Job into P0 Virtual Address Space

  3.3     Mapping Process Stacks and Context Data into P1 Address Space

  3.4     Allocating Physical Memory
    3.4.1      Allocating Physical Memory and Mapping it into P0 or P1 Space (the ALLOCATE MEMORY Routine)
    3.4.2      Allocating Physical Memory and Mapping it into S0 Space (the ALLOCATE SYSTEM REGION Routine)
    3.4.3      Deallocating Physical Memory Mapped into P0 or P1 Space (the FREE MEMORY Routine)
    3.4.4      Deallocating Physical Memory Mapped into S0 Space (the FREE SYSTEM REGION Routine)
    3.4.5      Obtaining the Size of Memory (the MEMORY SIZE Routine)

  3.5     Loading a VAXELN System Image onto a KA800 Processor

  4      Process Synchronization

  4.1     VAXELN WAIT Routines

  4.2     Waiting on an Object

  4.3     Using Time Values to Synchronize Process Execution
    4.3.1      Waiting on a Time
    4.3.2      Setting and Retrieving the System Time

  4.4     Using Process Completion to Synchronize Execution

  4.5     Synchronizing Process Execution by Waiting for a Resource
    4.5.1      Creating a Semaphore Object
    4.5.2      Waiting On and Signaling a Semaphore Object
    4.5.3      Deleting a Semaphore Object
    4.5.4      Using Mutexes to Optimize Waiting and Signaling Operations

  4.6     Using Events to Synchronize Process Execution
    4.6.1      Creating an Event Object
    4.6.2      Waiting On, Signaling, and Clearing an Event Object
    4.6.3      Deleting an Event Object

  5      Communication

  5.1     Sharing Module-Level Data

  5.2     Sharing Packets of Data Using Queues
    5.2.1      Absolute Queues
    5.2.2      Self-Relative Queues
    5.2.3      Using Queues in Memory Allocated with ALLOCATE SYSTEM REGION

  5.3     Passing Messages
    5.3.1      Sending and Receiving a Datagram Message
    5.3.2      Establishing a Circuit
    5.3.3      Sending and Receiving a Message Over a Circuit
    5.3.4      Messages and Message Objects
    5.3.5      Port Objects
    5.3.6      Named Message Ports
    5.3.7      Normal and Expedited Messages
      5.3.7.1      Sending and Receiving a Message on the Normal Flow
      5.3.7.2      Sending and Receiving an Expedited Message
    5.3.8      Choosing Datagrams or Circuits
    5.3.9      Programming with Circuits
    5.3.10     Port Limits and Flow Control
      5.3.10.1     Flow Control with Datagrams
      5.3.10.2     Flow Control with Circuits
    5.3.11     Kernel Services for Message Transmission

  5.4     Sharing Memory Areas
    5.4.1      Creating and Mapping an Area
      5.4.1.1      Creating an Area and Mapping the Area into P0 Virtual Memory
      5.4.1.2      Mapping an Existing Area into P0 Virtual Memory
    5.4.2      Synchronizing Access to Areas with Events
    5.4.3      Synchronizing Access to Areas with Semaphores
    5.4.4      Using Area Lock Variables to Optimize Waiting and Signaling Operations
    5.4.5      Using Areas to Synchronize Job Execution
    5.4.6      Sharing Packets of Data in an Area Using Queues
    5.4.7      Deleting Areas
    5.4.8      Summary of Area Routines

  6      Device Handling

  6.1     Designing a Device Driver

  6.2     Creating and Deleting Device Objects

  6.3     Handling Device Interrupts
    6.3.1      Waiting for an ISR to Service a Device Interrupt
    6.3.2      Signaling the Device Object After Service Completion

  6.4     Synchronizing Access to the Device Communication Region

  6.5     Setting the Job Priority of a Device Driver

  6.6     Setting a Driver Job's Processor Eligibility

  6.7     Reading and Writing Register Data

  6.8     Controlling DMA Devices
    6.8.1      Allocating, Loading, and Freeing Map Registers
    6.8.2      Allocating and Freeing Buffered Data Paths
    6.8.3      Mapping and Unmapping Memory Buffers
    6.8.4      Returning a Variable's Physical Address

  6.9     Coding VAXBI Bus Device Drivers

  6.10    Executing Routines in Kernel Mode

  6.11    Handling Power-Failure Recovery

  7      Exception Handling

  7.1     VAX Stack Architecture

  7.2     Exceptions in VAXELN Systems
    7.2.1      Exception-Handler Arguments
    7.2.2      Continue and Resignal Operations
    7.2.3      Unwind Operation
    7.2.4      Multiple Concurrent Exceptions

  7.3     Raising Exceptions
    7.3.1      Kernel Routine Failure Exceptions
    7.3.2      Asynchronous Exceptions

  7.4     Exception-Handling Routines

  7.5     Status Codes

  7.6     Using Runtime Messages in Application Programs
    7.6.1      VAXELN Message Files
    7.6.2      Constructing Messages
    7.6.3      Using Message Files with Application Programs
    7.6.4      Retrieving Message Text
    7.6.5      Displaying VAXELN Message Text on VMS Systems

  A   Status Values/Exception Names

  B   Machine-Check Stack Frames

  B.1     Obtaining a Machine-Check Stack Frame

  B.2     MicroVAX I

  B.3     MicroVAX II and 2000; VAXstation II and 2000; KA800

  B.4     rtVAX 300; MicroVAX 3 nnn ; VAX 4000 200; VAXstation 3 nnn ; VAX 6000-2 nn 3 nn

  B.5     VAX 6000-4 nn and VAX 6000-5 nn Series

  B.6     VAX 8200 and 8250

  B.7     VAX 8500, 8550, 8700, 8800, and 8810

  B.8     VAX-11/730

  B.9     VAX-11/750

  B.10   VAXstation 4000 Model 400

  C   VMS Emulation Routines

  C.1     VMS Emulation Routine Summary

  C.2     Calling VMS Emulation Routines

  C.3     VMS System Service Emulation Routine Descriptions

  C.4     LIB$ Emulation Routine Descriptions

  C.5     STR$ Emulation Routine Description

  EXAMPLES

  2-1        Creating a Process (CREATE PROCESS)

  2-2        Setting Job Eligibility (SET JOB ELIGIBILITY)

  2-3        Obtaining the JCB Address (GET JCB)

  3-1        Loading a VAXELN Image into a KA800 (LOAD KA800 PROCESSOR)

  4-1        Setting and Getting the System Time and Elapsed Time (SET TIME, GET TIME, and GET UPTIME)

  4-2        Creating a Semaphore Object (CREATE SEMAPHORE)

  4-3        Creating, Locking, and Unlocking a Mutex (CREATE MUTEX, LOCK MUTEX, and UNLOCK MUTEX)

  4-4        Creating an Event Object (CREATE EVENT)

  5-1        Using Queues for Process Communication (START QUEUE, INSERT ENTRY, and REMOVE ENTRY)

  5-2        Starting a Self-Relative Queue (START QUEUE RELATIVE)

  5-3        Creating a Port Object (CREATE PORT)

  5-4        Sending a Message (CREATE MESSAGE and SEND)

  5-5        Connecting a Circuit (CONNECT CIRCUIT)

  5-6        Waiting for and Accepting a Circuit Request (ACCEPT CIRCUIT)

  5-7        Requesting Multiple Connections

  5-8        Disconnecting the Partner Port (DISCONNECT CIRCUIT)

  5-9        Creating an Area Object with a Counting Semaphore (CREATE AREA SEMAPHORE)

  5-10       Synchronizing Access to Areas with Events (CREATE AREA EVENT)

  5-11       Synchronizing Job Execution with Semaphores

  6-1        Creating a Device Object (CREATE DEVICE)

  6-2        Entering Kernel Mode (ENTER KERNEL CONTEXT)

  7-1        Reestablishing a Previous Stack Environment (UNWIND)

  7-2        Using Message Files

  7-3        Getting Status Text

  FIGURES

  1-1        Loosely Coupled Multiprocessing Configuration

  1-2        Tightly Coupled Symmetric Multiprocessing Configuration

  2-1        Valid Process State Transitions

  2-2        Job and Process Priorities

  2-3        Combined Priority Representation

  3-1        Mapping the System Image and Job Components into Virtual Memory

  3-2        System Region

  3-3        Program Region

  3-4        Control Region

  5-1        Sending a Local Datagram

  5-2        Sending a Remote Datagram

  5-3        Sending a Message over a Local Circuit

  5-4        Sending a Message over a Remote Circuit

  7-1        A Routine's Stack Frame

  7-2        A Frame Structure After a Routine Call

  7-3        Call Frame Block

  7-4        Signal Arguments

  7-5        Mechanism Arguments

  B-1        Machine-Check Stack Frame for MicroVAX I Processors

  B-2        Machine-Check Stack Frame for MicroVAX II and 2000, VAXstation II and 2000, and KA800 Processors

  B-3        Machine-Check Stack Frame for rtVAX 300, MicroVAX 3 nnn Series, VAX 4000 Model 200, VAXstation 3100, 3200, and 350S

  B-4        Machine-Check Stack Frame for VAX 6000-4 nn and VAX 6000-5 nn Series Processors

  B-5        Machine-Check Stack Frame for VAX 8200 and 8250 Processors

  B-6        Machine-Check Stack Frame for VAX 8500, 8550, 8700, 8800, and 8810 Processors

  B-7        Machine-Check Stack Frame for VAX-11/730 Processors

  B-8        Machine-Check Stack Frame for VAX-11/750 Processors

  B-9        Machine-Check Stack Frame for the VAXstation 4000 Model 400

  TABLES

  1-1        Kernel Objects

  1-2        Optimized Data Structures

  2-1        Process States

  2-2        Job Priorities of VAXELN Toolkit Program Images

  2-3        Kernel Services for Processes and Jobs

  5-1        Kernel Services for Message Transmission

  5-2        Area Routines

  6-1        Interrupt Priority Levels

  7-1        Exception Handling Routines

  7-2        VAXELN Message Files

  A-1        Status Values/Exception Names

  B-1        Machine-Check Type Codes for MicroVAX I Processors

  B-2        Machine-Check Type Codes for MicroVAX II and 2000, VAXstation II and 2000, and KA800 Processors

  B-3        Machine-Check Type Codes for rtVAX 300, MicroVAX 3 nnn VAX 4000 Model 200 Series, VAXstation 3100, 3200, and 3500,S

  B-4        Machine-Check Type Codes for VAX 6000-4 nn and VAX 6000-5 nn Series Processors

  B-5        Machine-Check Stack Frame Contents for VAX 8500, 8550, 8700, 8800, and 8810 Processors

  B-6        Machine-Check Error Type Codes for VAX-11/730 Processors

  B-7        Machine-Check Error Codes for VAX-11/750 Processors

  C-1        VMS System Service Emulation Routines

  C-2        VMS Runtime Library Emulation Routines

  C-3        SYS$ASCTIM System Service Call Format

  C-4        SYS$FAO System Service Call Format

  C-5        SYS$GETIM System Service Call Format

  C-6        SYS$NUMTIM System Service Call Format

  C-7        SYS$PUTMSG System Service Call Format

  C-8        SYS$UNWIND System Service Call Format

  C-9        LIB$ADD_TIMES Routine Call Format

  C-10       LIB$ADDX Routine Call Format

  C-11       LIB$ANALYZE_SDESC Routine Call Format

  C-12       LIB$CREATE_USER_VM_ZONE Routine Call Format

  C-13       LIB$CREATE_VM_ZONE Routine Call Format

  C-14       LIB$CVT_DTB Routine Call Format

  C-15       LIB$CVT_HTB Routine Call Format

  C-16       LIB$CVT_OTB Routine Call Format

  C-17       LIB$DELETE_VM_ZONE Routine Call Format

  C-18       LIB$EDIV Routine Call Format

  C-19       LIB$EMUL Routine Call Format

  C-20       LIB$FLT_UNDER Routine Call Format

  C-21       LIB$FREE_VM Routine Call Format

  C-22       LIB$FREE_VM_PAGE Routine Call Format

  C-23       LIB$GET_INPUT Routine Call Format

  C-24       LIB$GET_VM Routine Call Format

  C-25       LIB$GET_VM_PAGE Routine Call Format

  C-26       LIB$INT_OVER Routine Call Format

  C-27       LIB$LEN Routine Call Format

  C-28       LIB$MATCH_COND Routine Call Format

  C-29       LIB$MULT_DELTA_TIME Routine Call Format

  C-30       LIB$MULTF_DELTA_TIME Routine Call Format

  C-31       LIB$PUT_OUTPUT Routine Call Format

  C-32       LIB$RESET_VM_ZONE Routine Call Format

  C-33       LIB$SCOPY_DXDX Routine Call Format

  C-34       LIB$SCOPY_R_DX Routine Call Format

  C-35       LIB$SIGNAL Routine Call Format

  C-36       LIB$SIG_TO_RET Routine Call Format

  C-37       LIB$STOP Routine Call Format

  C-38       LIB$SUB_TIMES Routine Call Format

  C-39       LIB$SUBX Routine Call Format

  C-40       STR$ANALYZE_SDESC Routine Call Format