Fluke: Flexible -kernel Environment Application ... - CiteSeerX

D R A F T

Fluke: Flexible -kernel Environment Application Programming Interface Reference Bryan Ford Mike Hibler The Flux Project Department of Computer Science University of Utah Salt Lake City, UT 84112 [email protected] http://www.cs.utah.edu/projects/flux/

September 3, 1996

This speci cation is guaranteed to change! The interface and terminology are still evolving, and will certainly change before a formal release of the prototype kernel implementing this interface. A companion document, \Fluke: Design Principles and Rationale," describes the Fluke execution architecture in detail. It will be available soon.

1

Contents

1 Introduction

1.1 Object State 1.2 Object Invocations

5

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

2 Thread 2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9 2.10 2.11 2.12 2.13 2.14 2.15 2.16 2.17 2.18

Overview State References

uke thread create: create a new thread

uke thread destroy: destroy a thread

uke thread disable exceptions: prevent exceptions in the current thread

uke thread enable exceptions: allow exceptions in the current thread

uke thread get saved state: retrieve the exception state of a thread

uke thread get state: retrieve the current state of a thread

uke thread interrupt: interrupt another thread

uke thread move: move a thread object from one location to another

uke thread reference: associates a reference with a thread

uke thread return from exception: return from an exception handler

uke thread self: nd the current thread

uke thread set handlers: register the exception handling routines for a thread.

uke thread set saved state: restores exception state of a thread

uke thread set state: set the current state of a thread object

uke thread schedule: schedule another thread to run

7

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : :

: : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : :

3 Task 3.1 3.2 3.3 3.4 3.5 3.6 3.7 3.8 3.9

Overview State References

uke task create: create a new task

uke task destroy: destroy a task

uke task get state: retrieve the current state of a task object

uke task move: move a task object from one location to another

uke task reference: associates a reference with a task

uke task set state: set the current state of a task object

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

Overview State References

uke region create: create a new memory region

uke region destroy: destroy a memory region

uke region get state: retrieve the current state of a region object

uke region move: move a region object from one location to another

uke region protect: change the access permissions of a memory region

uke region reference: associates a reference with a memory region

uke region search: search for objects in a memory region

uke region set state: set the current state of a region object

25 25 25 26 27 28 29 30 31

32

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

2

7 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 24

25

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

4 Regions 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10 4.11

5 5

32 32 32 33 34 35 36 37 38 39 41

5 Mappings 5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9

Overview State References

uke mapping create: create a new memory mapping

uke mapping destroy: destroy a memory mapping

uke mapping get state: retrieve the current state of a mapping object

uke mapping move: move a mapping object from one location to another

uke mapping protect: change the protection of an address mapping

uke mapping set state: set the current state of a mapping object

42

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : :

: : : : : : : : : : : : : : :

6 Ports 6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9

Overview State References

uke port create: create a new port

uke port destroy: destroy a port

uke port get state: retrieve the current state of a port

uke port move: move a port object from one location to another

uke port reference: associates a reference with a port

uke port set state: set the current state of a port object

50

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

7 Port Sets 7.1 7.2 7.3 7.4 7.5 7.6 7.7

Overview State References

uke pset create: create a new port set

uke pset destroy: destroy a port set

uke pset move: move a port set object from one location to another

uke pset reference: associates a reference with a port set

50 50 50 51 52 53 54 55 56

57

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : :

8 Interprocess Communication

8.1 Overview 8.2 IPC parameters 8.2.1 IPC buer descriptors 8.2.2 Send parameters 8.2.3 Receive parameters 8.3 uke ipc call: make a synchronous idempotent call to a port 8.4 uke ipc client connect send: create a reliable connection to a server 8.5 uke ipc client connect send over receive: perform a reliable RPC to a server 8.6 uke ipc reply: reply to an idempotent call 8.7 uke ipc send: send a one-way message to a port 8.8 uke ipc setup wait receive: set up a server thread and wait for incoming IPC invocations 8.9 uke ipc side alert: send an interrupt on a reliable IPC connection 8.10 uke ipc side disconnect: destroy a reliable IPC connection 8.11 uke ipc side over receive: reverse the transfer direction of a reliable IPC connection 8.12 uke ipc side receive: receive data through reliable IPC 8.13 uke ipc side send: send data across a reliable IPC connection 8.14 uke ipc wait receive: wait on a port set for incoming IPC invocations

57 57 57 58 59 60 61

62

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

3

42 42 42 44 45 46 47 48 49

62 62 62 62 63 64 66 68 70 71 72 74 75 76 78 80 81

9 Mutexes 9.1 9.2 9.3 9.4 9.5 9.6 9.7 9.8 9.9 9.10 9.11 9.12

83

Overview State References

uke mutex create: create a new mutex

uke mutex destroy: destroy a mutex

uke mutex get state: retrieve the current state of a mutex

uke mutex lock: lock a mutex object

uke mutex move: move a mutex object from one location to another

uke mutex reference: associates a reference with a mutex

uke mutex set state: set the current state of a mutex object

uke mutex trylock: attempt to lock a mutex object

uke mutex unlock: lock a mutex object

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

10 Condition Variables

10.1 Overview 10.2 State 10.3 References 10.4 uke cond broadcast: broadcast on a condition variable object 10.5 uke cond create: create a new condition variable 10.6 uke cond destroy: destroy a condition variable 10.7 uke cond get state: retrieve the current state of a condition variable 10.8 uke cond move: move a condition variable object from one location to another 10.9 uke cond reference: associates a reference with a condition variable 10.10 uke cond set state: set the current state of a condition variable object 10.11 uke cond signal: signal on a condition variable object 10.12 uke cond wait: wait on a condition variable object

93

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : :

11 References

11.1 Overview 11.2 State 11.3 References 11.4 uke ref check: determine if a reference is non-NULL 11.5 uke ref compare: determine if two references are equivalent 11.6 uke ref copy: make a copy of a reference object 11.7 uke ref create: create a new reference object 11.8 uke ref destroy: destroy a reference 11.9 uke ref move: move a reference object from one location to another 11.10 uke ref type: return the type of an object associated with a reference

93 93 93 94 95 96 97 98 99 100 101 102

103

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : :

: : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : : :

4

83 83 83 84 85 86 87 88 89 90 91 92

: : : : : : : : : : : : :

103 103 103 104 105 106 107 108 109 110

1 Introduction This chapter describes the actual application programming interface (API) that is exposed to application code running in Fluke tasks. It is de ned in terms of C function calls and de nitions, although it can be accessed from other languages as well with appropriate glue. The API is divided into two basic parts: the set of functions available to operate on active Fluke objects, and the data structures storing the state of inactive (pickled) Fluke objects. The processor-architectureindependent aspects of each of these are de ned in the following two sections; following these descriptions are sections describing processor-speci c details of the API, as well as processor-speci c object types and enhancements. Note that the C-language type names used in the function prototypes are the same as the type names of the corresponding pickled data structures. This is for convenience only; the rule still applies that (unless otherwise speci ed) the contents of these structures must not be accessed while an object is active.

1.1 Object State

The concept of exporting and later importing state... fluke object get state and fluke object set state... Two types of state are de ned for an object: \simple" state that can be represented as raw bits in the context of a task address space, and inter-object links which cannot. For each object type, a fluke object state structure is de ned to encapsulate the simple state if there is any. A reference object is used to represent each inter-object link. Object references in state (reference objects)... The state of an object does not include indication of others referencing it (e.g. mappings referencing regions)...

Fix: Is this section needed or appropriate here?

1.2 Object Invocations

This section describes, for each de ned Fluke object type, the set of object invocations available for that type. Except where otherwise speci ed, all invocation parameters that are pointers to active objects must point to objects that appear in the current task, i.e. in the same task as the thread making the invocation. There are a set of function common to all Fluke object types:

uke object create: Creates an object of the speci ed type. The caller provides a pointer to a fluke object structure which will hold the user portion of the uke object's state. This memory should be aligned naturally for the object type 1 and should contain no other objects. After return from a create call, the memory occupied by the object structure should only be used in object invocations, and not accessed directly (the result of direct accesses is unde ned). Objects have an initial default state, but in many cases that default state is not very useful and the new object is not \useable" until new state has been set with fluke object set state. Objects can only be created in memory which has FLUKE PROT CREATE OB and FLUKE PROT WRITE permissions enabled. If not enabled, attempts to create objects will cause a synchronous exception (\page fault") to be sent to the region keeper or, failing that, to the thread or its associated task keeper.

uke object destroy: Destroys an object. The caller provided pointer should reference a valid object of the correct type. This implies that the call will also fail if the pointer is to an object with corrupted state. The only way to destroy \corrupt" objects is via fluke region search. 2 After an object is destroyed, the contents of the memory occupied by the object is unde ned and the memory is once again directly accessible. 1 Natural alignment means aligned to the object size. Since object sizes are always a power of two and less than one page, this ensures that an object will never span a page boundary 2 Rationale: We could just de ne the interface such that fluke object destroy always succeeds, regardless of the state of the object. However, the same capability would still be needed for fluke region search anyway, so for now we will see if we can get by with just the latter.

5

Objects can only be destroyed in memory which has FLUKE PROT WRITE permission enabled. If not enabled, attempts to destroy objects will cause synchronous page fault exceptions.

uke object move: Moves an object from one virtual address to another in the same task. The \from" argument must be a pointer to a valid object of the correct type. The \to" argument must be a pointer to raw memory as in a create call. After the call, the contents of the memory occupied by the \from" object is unde ned and the memory is once again directly accessible. Moving an object requires FLUKE PROT WRITE permission to the source memory, FLUKE PROT CREATE OB and FLUKE PROT WRITE to the destination. If the appropriate permissions are not allowed, attempts to move objects will cause synchronous page fault exceptions.

uke object reference: Associates a reference object with an object of the given type. The caller provides a pointer to a valid object of the appropriate type and a pointer to a valid reference object created via fluke ref create. The caller must have FLUKE PROT WRITE permission for both the object being referenced and the reference object itself. If the appropriate permissions are not allowed, attempts to reference objects will cause synchronous page fault exceptions.

uke object get state: Returns the complete state of an object. The object itself is unaected by the

call. The caller provides a pointer to a fluke object state structure for any simple state, and a list of pointers to valid reference objects for inter-object state. After the call, the state structure will be lled in and the reference objects will be associated with whatever the corresponding inter-object links referred to. The simple state pointer or any of the reference pointers may be zero, in which case the corresponding state is not returned. Calls failing due to \insanity" conditions leave the contents of any state structure unde ned and reference objects possibly modi ed. The caller must have FLUKE PROT READ permission to the object. Otherwise, a synchronous page fault exception is generated.

uke object set state: Loads new state for an object. The arguments are identical to those of the corre-

sponding fluke object get state call. a pointer to a simple state structure and a list of pointers to valid reference objects. Any of the pointers may be zero, in which case the corresponding state is not loaded. All reference objects are copied; i.e. after the call, any references passed in will still be valid and can safely be destroyed. The eect of loading corrupt object state is unde ned, the call may or may not return an error and the resulting state of the object is unde ned. Calls failing due to \insanity" conditions leave the target object in an unde ned, though always valid, state. For example, an object's references to other objects may be invalidated. The caller must have FLUKE PROT WRITE permission to the object. Otherwise, a synchronous page fault exception is generated.

6

2 Thread

2.1 Overview

This section describes the Fluke API operations related to threads. Threads are the active entities in Fluke. They represent independent ows of control and contain CPU register state among other things. A thread requires an address space context (task) and CPU resources (a schedular) to run. Many thread operations cannot be performed on the currently running thread (fluke thread destroy, fluke thread get state, fluke thread set state, fluke thread interrupt) while some can only be performed on the current thread (fluke thread enable exceptions, fluke thread disable exceptions, fluke thread set handlers, fluke thread get saved state, fluke thread set saved state, fluke thread return from Consult the appropriate API section for details. A running thread is stopped whenever its state is collected with fluke thread get state. It will remain stopped until a fluke thread set state call with the FLUKE THREAD STOPPED bit cleared is made. A running thread may also be stopped by clearing its task or schedular reference or unmapping the thread object itself. 3 Hence, a thread must have a task and schedular reference and the thread object must be mapping at the proper location in the associated task, and the FLUKE THREAD STOPPED bit must be cleared, in order to run.

2.2 State

The processor architecture-independent portion of a thread object consists of:

uke thread state

g;

struct vm offset t integer t unsigned fluke fluke fluke fluke fluke

ref ref ref ref ref

t t t t t

f

; /* virtual address of thread object ; /* scheduler-assigned thread id /* general thread ags

thread va sched val flags

;

*/ */ */

*task ref; *scheduler ref; *waiting for ref; *client ref; *server ref;

thread va is the virtual address in the associated task at which the thread object must be mapped in

order to run.

sched val is a scheduler assigned thread identi er.

ags contains a number of thread state bits. Most are architecture speci c, but one is of general use.

FLUKE THREAD STOPPED is set whenever a thread was stopped at the time its state was collected. Clearing the bit when restoring a thread's state, may not actually resume the thread (that also depends on its task and schedular reference) but is a prerequisite to doing so. task ref is a reference to the task object to which the thread belongs. If task ref is NULL the thread cannot execute. An otherwise runnable thread will block on its thread object. scheduler ref is a reference to the port to which the thread sends an idempotent IPC to request CPU time. If NULL, the thread can only run using donated time from another thread; e.g., as the server in an idempotent or reliable IPC call. waiting for ref is a reference to a number of possible objects indicating that the thread is blocked waiting for the object. The referenced object may be:  Another thread, indicating that the thread is waiting on an IPC operation in progress.  A port object, indicating that the thread attempting to initiate IPC and is waiting for a server thread to become available.  A port set object, indicating that the thread is a server thread and is waiting for an invocation from a client thread.  A mutex object, indicating that the thread is waiting for the mutex to become available. 3 Unmapping the thread object has the same eect as giving the thread a NULL task reference. However, the latter would require a fluke thread set state call which cannot be done on a running thread.

7

A condition object, indicating that the thread is waiting for the condition to be signaled or broadcast. Note that the application does not need to save this reference in order preserve the \critical" state of the thread; it can be regenerated at any time from the thread's CPU state. For example, if the thread is waiting in an idempotent IPC, then the thread's saved program counter will point to the Fluke fluke ipc call operation entrypoint and the saved register state will contain all the information necessary to restart the operation. client ref is a reference to a thread object. If non-NULL and the referenced thread's server ref points to this thread, then this thread is acting in the server role of a reliable IPC connection with the referenced thread. server ref is a reference to a thread object. If non-NULL and the referenced thread's client ref points to this thread, then this thread is acting in the client role of a reliable IPC connection with the referenced thread. 

2.3 References

A thread object may reference:  tasks: The task ref reference.  threads: The waiting for ref, client ref, or server ref references.  ports: The scheduler ref or waiting for ref references.  port sets: The waiting for ref reference.  mutexes: The waiting for ref reference.  condition variables: The waiting for ref reference. A thread object may be referenced by:  threads: The thread object waiting for ref, client ref, or server ref references.  mutexes: The mutex object owner ref reference.

8

2.4 uke thread create: create a new thread Synopsis

fluke error t

uke thread create( uke thread t *new thread);

Description

The fluke thread create operation creates a new thread. All of the new thread's references, such as its task and scheduler references, will initially be null. Thus, the new thread will not be able to run until its state is initialized using fluke thread set state. The initial values of all other thread state, such as the thread's processor registers, are unde ned. Parameters

new thread : A pointer to the address in the current task's address space at which to create the

new thread object.

Errors

If any of the following errors is detected, the appropriate error code is returned: FLUKE NO MEMORY: Insucient kernel resources were available. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new thread. FLUKE INSANITY NOT ALIGNED: new thread is not properly aligned for a thread object. Related Information fluke thread set state

9

2.5 uke thread destroy: destroy a thread

Synopsis void

uke thread destroy(fluke thread t *thread);

Description

Destroys a thread created with fluke thread create. The caller must ensure that the target thread is not currently running; otherwise the results are unde ned. This means by implication that a thread cannot call fluke thread destroy on itself. Any references to the destroyed thread object become invalid. Any other thread performing an idempotent IPC to this thread will be woken up and will receive an error return (Fix: FLUKE INVALID DEST?) If the thread being destroyed is involved in reliable IPC, an alert is sent to the other threads involved and the IPC connections are broken. The other threads involved will receive errors if they attempt further IPC with this thread. If any other threads are waiting on this thread, they are woken up immediately. Parameters

thread : The thread to destroy. The thread must not be running. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: thread does not point to an active object. FLUKE INSANITY NOT THREAD: The object pointed to by thread is not a thread object. FLUKE INSANITY INVALID OBJECT: The state of the thread object has become invalid. FLUKE INSANITY CURRENT THREAD: A thread attempted to destroy itself. Related Information fluke thread create

10

2.6 uke thread disable exceptions: prevent exceptions in the current thread

Synopsis void

uke thread disable exceptions( uke thread t *cur thread);

Description

This operation turns o the exception enable ag in the current thread. Thereafter, until a subsequent call to fluke thread enable exceptions, any asynchronous exceptions that are posted to this thread will be deferred until exceptions are enabled again, and any synchronous exceptions that occur in this thread will cause the thread to make an idempotent IPC to its task's keeper port. Parameters

cur thread : A pointer to the thread object representing the current thread, e.g. as returned by

.

fluke thread self 4

Related Information

,

,

,

fluke thread enable exceptions fluke thread interrupt fluke thread set handlers fluke ipc side alert

4 Rationale: Finding the current thread is likely to be somewhat expensive, even on Fluke implementations that do it entirely in user mode. Since these operations will generally be called in enable/disable pairs, it is likely to be more ecient if the caller calls fluke thread self once and passes the same pointer each time.

11

2.7 uke thread enable exceptions: allow exceptions in the current thread Synopsis void

uke thread enable exceptions( uke thread t *cur thread);

Description

This operation turns on the exception enable ag in the current thread. Thereafter, until a subsequent call to fluke thread disable exceptions, any synchronous or asynchronous exceptions that occur in this thread will be dispatched to the thread's exception handler. Parameters

cur thread : A pointer to the thread object representing the current thread, e.g. as returned by

.

fluke thread self 5

Related Information

,

,

,

fluke thread disable exceptions fluke thread interrupt fluke thread set handlers fluke ipc side alert

5 Rationale: Finding the current thread is likely to be somewhat expensive, even on Fluke implementations that do it entirely in user mode. Since these operations will generally be called in enable/disable pairs, it is likely to be more ecient if the caller calls fluke thread self once and passes the same pointer each time. Furthermore, an extremely common use of this routine will be to re-enable exceptions in an exception handler after the saved state has been pushed on the stack; in this case, the exception handler already has a pointer to the current thread, because it was passed to the exception handler when it was invoked in the rst place.

12

2.8 uke thread get saved state: retrieve the exception state of a thread

Synopsis void

uke thread get saved state(fluke thread t *cur thread, [out] struct uke thread saved state

*saved state);

Description

Returns an architecture-speci c subset of the state of the current thread. In particular, it returns only the CPU state that the kernel needed to save prior to changing it to invoke the exception handler. For example, on most architectures, this would include the instruction and stack pointer values at the time of the fault. It is the responsibility of the exception handler to save all other volatile state (e.g., caller-save registers). This call is only necessary if the exception handler wants to change the value of some element of the saved state. Otherwise, the kernel saved values will be automatically restored on a fluke thread return from exception Parameters

cur thread : A pointer to the thread object representing the current thread, e.g. as returned by

. saved state : A pointer to the architecture-speci c saved state structure. fluke thread self 6

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NOT CURRENT THREAD: Thread speci ed was not the current thread. Related Information

,

,

fluke thread set handlers fluke thread set saved state fluke thread return from exception

6 Rationale: Finding the current thread is likely to be somewhat expensive, even on Fluke implementations that do it entirely in user mode. Since these operations will generally be called in get/set pairs, it is likely to be more ecient if the caller calls fluke thread self once and passes the same pointer each time.

13

2.9 uke thread get state: retrieve the current state of a thread Synopsis

uke thread get state(fluke thread t *thread, [out] fluke thread state *state, [out]

void fluke ref t *task ref fluke ref t *client ref

, [out] fluke ref t *scheduler ref, [out] fluke ref t *waiting for ref, [out] , [out] fluke ref t *server ref);

Description

This operation retrieves the application-visible state of a thread. The thread itself is unaected by the operation. The caller must ensure that the target thread is not currently running; otherwise the results are unde ned. Parameters

thread : The thread whose state is to be retrieved. The thread must not be running. state : If non-null, the structure to ll in with the simple (non-reference) thread state. task ref : If non-null, the address of a reference object to associate with the thread's task object. scheduler ref : If non-null, the address of a reference object to associate with the thread's scheduler

port object.

waiting for ref : If non-null, the address of a reference object to associate with the object the thread

is currently waiting for. client ref : If non-null, the address of a reference object to associate with the thread's client thread object. server ref : If non-null, the address of a reference object to associate with the thread's server thread object.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: thread does not point to an active object. FLUKE INSANITY NOT THREAD: The object pointed to by thread is not a thread object. FLUKE INSANITY INVALID OBJECT: The state of the thread object has become invalid. FLUKE INSANITY NOT REF: One or more of the reference object parameters was not a pointer to a reference object. FLUKE INSANITY RACE CONDITION: An illegal race condition with another thread was detected on one of the objects speci ed as parameters to this call. FLUKE INSANITY CURRENT THREAD: A thread attempted to get its own state. Related Information fluke thread set state

14

2.10 uke thread interrupt: interrupt another thread Synopsis void

uke thread interrupt(fluke thread t *thread);

Description

This operation posts a software interrupt to the speci ed thread. If the thread is currently running with exceptions enabled (i.e. its exception ag turned on), the thread will take the software interrupt immediately. If the target thread is waiting for some event, it will be woken up so that it can take the interrupt. However, if the target thread's exception enable ag is not set, then the thread will not actually take the exception until it turns on its exception enable ag again. Parameters

thread : The thread to interrupt. The speci ed thread must not be the current thread; otherwise

the results are unde ned.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: thread does not point to an active object. FLUKE INSANITY NOT THREAD: The object pointed to by thread is not a thread object. FLUKE INSANITY INVALID OBJECT: The state of the thread object has become invalid. FLUKE INSANITY CURRENT THREAD: A thread attempted to interrupt itself. Related Information

,

,

fluke thread enable exceptions fluke thread disable exceptions fluke thread set handlers

15

2.11 uke thread move: move a thread object from one location to another

Synopsis void

uke thread move(fluke thread t *old addr, fluke thread t *new addr);

Description

Moves the speci ed active thread object from one location in the caller's address space to another. The caller must ensure that the target thread is not currently running; otherwise the results are unde ned. The memory addressed by new addr must not already contain any active Fluke objects. On return, the thread object will reside at new addr and the memory left behind at old addr will have unde ned contents. Parameters

old addr : The address of the thread object to move. new addr : The location in memory to which the thread is to be moved. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: old addr does not point to an active object. FLUKE INSANITY NOT THREAD: The object pointed to by old addr is not a thread object. FLUKE INSANITY INVALID OBJECT: The state of the thread object has become invalid. FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new addr. FLUKE INSANITY NOT ALIGNED: new addr is not properly aligned for a thread object.

16

2.12 uke thread reference: associates a reference with a thread

Synopsis void

uke thread reference(fluke thread t *thread, [out] fluke ref t *new thread ref);

Description

This function associates an active reference object with the speci ed active thread object. Parameters

thread : The thread object to which the new reference will refer. new thread ref : A pointer to a valid reference object. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: thread or new thread ref does not point to an active object. FLUKE INSANITY NOT THREAD: The object pointed to by thread is not a thread object. FLUKE INSANITY INVALID OBJECT: The state of the thread object has become invalid. FLUKE INSANITY NOT REF: new thread ref does not point to a valid reference object.

17

2.13 uke thread return from exception: return from an exception handler Synopsis void

uke thread return from exception( uke thread t *cur thread);

Description

Returns from an exception handler. Restores any saved state and resumes execution of the thread as indicated by the saved state. Execution will resume at the point of the exception if the saved state has not been modi ed. Parameters

cur thread : A pointer to the thread object representing the current thread, e.g. as returned by

.

fluke thread self 7

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NOT CURRENT THREAD: Thread speci ed was not the current thread. Related Information

,

,

,

fluke thread enable exceptions fluke thread disable exceptions fluke thread set handlers fluke thread get saved state fluke thread set saved state

,

7 Rationale: Finding the current thread is likely to be somewhat expensive, even on Fluke implementations that do it entirely in user mode. Since the current thread pointer is likely to be a part of the exception state passed to the handler, it is likely to be more ecient if the caller passes this pointer explicitly.

18

2.14 uke thread self: nd the current thread

Synopsis

uke thread self(void);

fluke thread t *

Description

This function returns a pointer to the thread object representing the current thread.

19

2.15 uke thread set handlers: register the exception handling routines for a thread.

Synopsis

uke thread set handlers(fluke thread t *cur thread, vm offset t trap handler, vm offset t interrupt handler, vm offset t client alert handler, vm offset t server alert handler);

void

Description

Provides exception handling routines for the various classes of exceptions a thread may handle by itself. Parameters speci c the addresses of function to be called when an exception of the particular class occurs. The exact calling convention for the handlers is architecture speci c. trap handler is the routine which is called on synchronous exceptions such as unresolved page faults or \insanity" conditions. interrupt handler is the routine which is called on asynchronous exceptions; i.e., those generated by fluke thread interrupt. client alert handler and server alert handler are the routines called asynchronous \alerts" are generated from either the client or server side of a reliable IPC connection. Parameters

cur thread : A pointer to the thread object representing the current thread, e.g. as returned by

.

fluke thread self 8

trap handler : Virtual address of the trap handler routine to use. interrupt handler : Virtual address of the interrupt handler routine to use. client alert handler : Virtual address of the client-side alert handler routine to use. server alert handler : Virtual address of the server-side alert handler routine to use. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: thread does not point to an active object. FLUKE INSANITY NOT THREAD: The object pointed to by thread is not a thread object. FLUKE INSANITY INVALID OBJECT: The state of the thread object has become invalid. Related Information

,

,

,

fluke thread enable exceptions fluke thread disable exceptions fluke thread interrupt fluke ipc side alert

8 Rationale:

Consistency with other cur thread routines?

20

2.16 uke thread set saved state: restores exception state of a thread Synopsis void

uke thread set saved state(fluke thread t *cur thread, struct uke thread saved state

*saved state);

Description

Restores the saved exception state of a thread; e.g., as returned by fluke thread get saved state. This state will be reloaded in the thread on fluke thread return from exception. Only required if the exception handler has modi ed some element of the saved state. Parameters

cur thread : A pointer to the thread object representing the current thread, e.g. as returned by

.

fluke thread self 9

saved state : A pointer to the architecture-speci c saved state structure. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NOT CURRENT THREAD: Thread speci ed was not the current thread. Related Information

,

,

fluke thread set handlers fluke thread get saved state fluke thread return from exception

9 Rationale: Finding the current thread is likely to be somewhat expensive, even on Fluke implementations that do it entirely in user mode. Since these operations will generally be called in get/set pairs, it is likely to be more ecient if the caller calls fluke thread self once and passes the same pointer each time.

21

2.17 uke thread set state: set the current state of a thread object

Synopsis

uke thread set state(fluke thread t *thread, fluke thread state *state, fluke ref t

void *task ref fluke ref t *scheduler *server ref

,

);

ref, fluke ref t *waiting for ref, fluke ref t *client ref, fluke ref t

Description

This operation can be used to set some or all of the application-visible state of a thread. The caller must ensure that the target thread is not currently running; otherwise the results are unde ned. All of the simple state in the thread, such as the CPU register contents, is loaded from the provided state structure. All references contained in the thread must be set individually from reference objects at the speci ed addresses. Any of the parameters except thread may be null, in which case the corresponding piece of thread state is not changed. See fluke thread get state for information on the format of the fluke thread state structure. Parameters

thread : The thread whose state is to be modi ed. The thread must not be running. state : If non-null, a pointer to a structure containing the simple (non-reference) state of the thread. task ref : If non-null, must point to an existing reference object which is to be inserted as the

thread's task reference. The reference object itself must be either null (invalid) or point to a task object. If a null reference is provided, the thread will not be able to run until a valid reference to a task is inserted again. If the task ref parameter itself is a null pointer (as opposed to a pointer to a null reference), then the thread's existing task reference is left unchanged. scheduler ref : If non-null, indicates the reference object to be inserted as the thread's scheduler port reference. The reference must either be null or must point to a port object. If scheduler ref is a null pointer, then the thread's scheduler reference is unchanged. waiting for ref : If this pointer is non-null, a reference to the object the thread is to wait for; See fluke thread get state for details. If the pointer is null, the thread remains waiting on the same object it was already waiting for. Note that this reference is not part of the \critical" state of a thread: it can be regenerated at any time based on the thread's current CPU state. If a null reference is inserted into this slot, then the thread will immediately wake up immediately after the fluke thread set state operation completes (assuming the thread has a valid task reference), contacting its scheduler if necessary to obtain CPU time. Even if a non-null reference is inserted here, a Fluke implementation may choose always to ignore it, treating it as if a null reference was provided and waking up the thread immediately. client ref : If non-null, indicates the reference to be inserted as the thread's client reference. The reference must either be null or must point to a thread object. If client ref is a null pointer, then the thread's client reference is unchanged. server ref : If non-null, indicates the reference to be inserted as the thread's server reference. The reference must either be null or must point to a thread object. If server ref is a null pointer, then the thread's server reference is unchanged. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: thread does not point to an active object. FLUKE INSANITY NOT THREAD: The object pointed to by thread is not a thread object. FLUKE INSANITY INVALID OBJECT: The provided thread state contains invalid information. 22

: One or more of the provided (non-null) reference parameters is not a valid reference object. FLUKE INSANITY NOT TASK REF: task ref is a valid reference object but not a task reference object. FLUKE INSANITY NOT PORT REF: scheduler ref is a valid reference object but not a port reference object. FLUKE INSANITY NOT THREAD REF: One or both of client ref or server ref is a valid reference object but not a thread reference object. FLUKE INSANITY RACE CONDITION: An illegal race condition with another thread was detected on one of the objects speci ed as parameters to this call. FLUKE INSANITY CURRENT THREAD: A thread attempted to set its own state. FLUKE INSANITY NOT REF

Related Information fluke thread get state

23

2.18 uke thread schedule: schedule another thread to run Synopsis void

uke thread schedule(fluke thread t *thread, fluke port t *sleep port, enum wakeup sensitivity);

Description

Donate CPU to another thread. Parameters

thread : Thread object to which to donate the CPU. sleep port : A port on which this thread waits for messages from other client threads. wakeup sensitivity : Indicates in which situations the scheduler should be woken. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: thread does not point to an active object. FLUKE INSANITY NOT THREAD: The object pointed to by thread is not a thread object. FLUKE INSANITY NOT PORT: The object pointed to by sleep port is not a port object. FLUKE INSANITY INVALID OBJECT: The state of the thread object has become invalid.

24

3 Task

3.1 Overview

Fix: \Tasks" are going to be renamed to \spaces." We need to do something with the keeper rst though.

It seems more appropriate for the thread instead of for a space since the region keeper is really intended as the address space fault handler.

This section describes the Fluke API operations related to tasks. Tasks provide an address space which serves as a rendezvous point for regions, mappings and threads. Regions are associated with tasks to \export" part of the address space to others (via region references). Mappings are associated with tasks and regions to \import" part of another task's address space into the current task. Threads use the task address space as a context in which to execute.

3.2 State

The processor architecture-independent portion of a task object consists of: fluke ref t

*keeper ref;

keeper ref is a port to which threads in the task will automatically make idempotent RPCs when they

encounter a synchronous exception condition that cannot be handled by the thread itself. If NULL, any thread causing an exception will block. Fix: What does it block on?

3.3 References

A task object may reference:  ports: The keeper ref reference. A task object may be referenced by:  threads: The thread object task ref reference.  regions: The region object task ref reference.  mappings: The mapping object task ref reference.

25

3.4 uke task create: create a new task

Synopsis

fluke error t

uke task create(fluke task t *new task);

Description

Creates a new empty task, initially devoid of memory mappings or threads. Some memory must be mapped into the task, and at least one thread must be created in the task before the task becomes useful. Parameters

new task : A pointer to the address in the current task's address space at which to create the new

task object. There must be no existing Fluke objects at this location; otherwise the results are unde ned.

Errors

If any of the following errors is detected, the appropriate error code is returned: FLUKE NO MEMORY: Insucient kernel resources were available. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new task. FLUKE INSANITY NOT ALIGNED: new task is not properly aligned for a task object. Related Information

,

fluke task destroy fluke thread create

26

3.5 uke task destroy: destroy a task

Synopsis void

uke task destroy(fluke task t *task);

Description

Destroys an active task created with fluke task create. All mapping objects targeting this task are detached and become eectively useless. Likewise, all region objects originating from this task are detached and all virtual address translations derived from the region are invalidated. Threads executing in the task are not automatically destroyed, but their task references become null and they stop running immediately since they have no address space in which to execute. Parameters

task : The task to destroy. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: task does not point to an active object. FLUKE INSANITY NOT TASK: The object pointed to by task is not a task object. FLUKE INSANITY INVALID OBJECT: The state of the task object has become invalid. Related Information fluke task create

27

3.6 uke task get state: retrieve the current state of a task object

Synopsis void

uke task get state(fluke task t *task, [out] fluke ref t *keeper ref);

Description

This operation retrieves the application-visible state of a task object, namely, the task's keeper port reference. Parameters

task : The task whose state is to be retrieved. keeper ref : The address of a reference object to associate with the task's keeper port. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: task does not point to an active object. FLUKE INSANITY NOT TASK: The object pointed to by task is not a task object. FLUKE INSANITY INVALID OBJECT: The state of the task object has become invalid. FLUKE INSANITY NOT REF: keeper ref is not a pointer to a reference object. Related Information fluke task set state

28

3.7 uke task move: move a task object from one location to another

Synopsis void

uke task move(fluke task t *old addr, fluke task t *new addr);

Description

Moves the speci ed active task object from one location in the caller's address space to another. The memory addressed by new addr must not already contain any active Fluke objects. On return, the task object will reside at new addr and the memory left behind at old addr will have unde ned contents. Parameters

old addr : The address of the active task object to move. new addr : The location in memory to which the task is to be moved. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: No object was found at old addr. FLUKE INSANITY NOT TASK: The object pointed to by old addr is not a task object. FLUKE INSANITY INVALID OBJECT: The state of the task object has become invalid. FLUKE INSANITY OBJECT EXISTS: An object already exists at new addr. FLUKE INSANITY NOT ALIGNED: new addr is not properly aligned for a task object.

29

3.8 uke task reference: associates a reference with a task

Synopsis void

uke task reference(fluke task t *task, [out] fluke ref t *new task ref);

Description

This function associates an active reference object with the speci ed active task object. Parameters

task : The active task object to which the new reference will refer. new task ref : A pointer to a valid reference object. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: task or new task ref does not point to an active object. FLUKE INSANITY NOT TASK: The object pointed to by task is not a task object. FLUKE INSANITY INVALID OBJECT: The state of the task object has become invalid. FLUKE INSANITY NOT REF: new task ref does not point to a valid reference object. Related Information fluke thread set state

30

3.9 uke task set state: set the current state of a task object Synopsis void

uke task set state(fluke task t *task, fluke ref t *keeper ref);

Description

This operation sets the application-visible state of a task object, namely, the task's keeper port reference. Subsequent exception IPCs generated by threads executing in the task will be sent to the new keeper port. Parameters

task : The task whose state is to be set. keeper ref : The address of a port reference object to be copied into the task's keeper port reference

slot.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: task or keeper ref does not point to an object. FLUKE INSANITY NOT TASK: The object pointed to by task is not a task object. FLUKE INSANITY NOT REF: The object at keeper ref is not a reference object. FLUKE INSANITY NOT PORT REF: The object at keeper ref is a reference object, but not a reference to a port. FLUKE INSANITY INVALID OBJECT: The state of an application object has become invalid, e.g. by being overwritten by garbage. Related Information fluke task get state

31

4 Regions

4.1 Overview

A Fluke region object de nes a contiguous range of virtual address space in a task that can be exported to other tasks to map into their address space via mapping objects. Regions are the primary mechanism by which memory manager tasks partition and control memory resources for the sub-task address spaces they manage. Region references can be created and passed in IPC messages to other tasks which can then insert those references into a mapping object to acquire access to the memory.

4.2 State

The processor architecture-independent portion of a region object consists of:

uke region state

g;

struct vm offset t vm size t fluke prot t fluke ref t fluke ref t

; ;

f

; /* region start VA in task /* size of region /* max protection allowed

start va size prot

*/ */ */

*task ref; *keeper ref;

start va and size de ne the extent of the region. Both may have processor architecture-speci c alignment

constraints.

max prot de nes the maximum access permissions that can be granted to any mapping object associated with the region. task ref is a reference to the task object over whose address space the region is de ned. If NULL, all mapping objects derived from this region will act as though the region's access permissions were zero; i.e. all accesses to those mappings will cause a synchronous exception to be sent to the region keeper. keeper ref is a reference to the port object to which fluke ipc call operations are made whenever a memory-related synchronous exception occurs; i.e., it identi es the page-fault handler for this memory region. A NULL keeper reference causes exceptions to be sent to the faulting thread as though a keeper existed but did not resolve the fault.

4.3 References

A region may reference:  tasks: The task ref reference.  ports: The keeper ref reference. A region may be referenced by:  mappings: The mapping object region ref reference.  references: Standalone region references used as capabilities.

32

4.4 uke region create: create a new memory region

Synopsis

fluke error t

uke region create(fluke region t *new region);

Description

Creates a new empty region, with no virtual memory association. Before it can be mapped, the region must be associated with a task address space using fluke region set state. Parameters

new region : A pointer to the address in the current task's address space at which to create the new

region object. There must be no existing Fluke objects at this location; otherwise the results are unde ned.

Errors

If any of the following errors is detected, the appropriate error code is returned: FLUKE NO MEMORY: Insucient kernel resources were available. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new region. FLUKE INSANITY NOT ALIGNED: new region is not properly aligned for a region object. Related Information fluke region set state

33

4.5 uke region destroy: destroy a memory region

Synopsis void

uke region destroy(fluke region t *region);

Description

Destroys a region created with fluke region create. All memory mappings into the region are automatically invalidated. Parameters

region : The region to destroy. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: region does not point to an active object. FLUKE INSANITY NOT REGION: The object pointed to by region is not a region object. FLUKE INSANITY INVALID OBJECT: The state of the region object has become invalid. Related Information fluke region create

34

4.6 uke region get state: retrieve the current state of a region object Synopsis

uke region get state(fluke region t *region, [out] fluke region state *state, [out]

void fluke ref t *task

ref, [out] fluke ref t *keeper ref);

Description

This operation retrieves the state of a region object. Parameters

region : The region whose state is to be retrieved. state : If non-null, the structure to ll in with the simple (non-reference) region state. task ref : If non-null, the address of a reference object to associate with the region's task object. keeper ref : If non-null, the address of a reference object to associate with the region's keeper port. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: region does not point to an active object. FLUKE INSANITY NOT REGION: The object pointed to by region is not a region object. FLUKE INSANITY INVALID OBJECT: The state of the region object has become invalid. FLUKE INSANITY NOT REF: task ref or keeper ref is not a pointer to a reference object. Related Information fluke region set state

35

4.7 uke region move: move a region object from one location to another Synopsis void

uke region move(fluke region t *old addr, fluke region t *new addr);

Description

Moves the speci ed active region object from one location in the caller's address space to another. The memory addressed by new addr must not already contain any active Fluke objects. On return, the region object will reside at new addr and the memory left behind at old addr will have unde ned contents. Parameters

old addr : The address of the active region object to move. new addr : The location in memory to which the region is to be moved. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: No object was found at old addr. FLUKE INSANITY NOT REGION: The object pointed to by old addr is not a region object. FLUKE INSANITY INVALID OBJECT: The state of the region object has become invalid. FLUKE INSANITY OBJECT EXISTS: An object already exists at new addr. FLUKE INSANITY NOT ALIGNED: new addr is not properly aligned for a region object.

36

4.8 uke region protect: change the access permissions of a memory region

Synopsis void

uke region protect(fluke region t *region, fluke prot t max prot);

Description

This operation modi es the maximum access allowed to a memory region. All mappings referencing the region either directly or indirectly are aected. A protection value of VM PROT NONE can be used to ush all mappings for a region. fluke region protect can be used to either restrict or relax the protection value. Note that this function is semantically equivalent to doing fluke region get state, changing the protection eld of the state and then calling fluke region set state. Parameters

region : The region to be changed. max prot : The maximum permissions to be left in any mappings derived from this region. If max prot is zero, then any derived mappings are eectively unusable by owning tasks. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: region does not point to an active object. FLUKE INSANITY NOT REGION: The object pointed to by region is not a region object. FLUKE INSANITY INVALID OBJECT: The state of the region object has become invalid. FLUKE INSANITY INVALID PROT: The requested protection, max prot, was invalid. Related Information

,

fluke region get state fluke region set state

37

4.9 uke region reference: associates a reference with a memory region

Synopsis void

uke region reference(fluke region t *region, [out] fluke ref t *new region ref);

Description

This function associates an active reference object with the speci ed active region object. Region references are used to associate mapping objects with regions. Parameters

region : The active region object to which the new reference will refer. new region ref : A pointer to a valid reference object. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: region or new region ref does not point to an active object. FLUKE INSANITY NOT REGION: The object pointed to by region is not a region object. FLUKE INSANITY INVALID OBJECT: The state of the region object has become invalid. FLUKE INSANITY NOT REF: new region ref does not point to a valid reference object. Related Information fluke mapping set state

38

4.10 uke region search: search for objects in a memory region

Synopsis

uke region search(fluke region t *region, [in/out] size, fluke obspec t *obs, [in/out] unsigned *count);

void

,

vm offset t *oset vm size t

Description

Search part or all of the address range covered by a memory region for active objects, inserting their addresses and types in the obs array. oset and size de ne the subset of the region to search. count must initially be set to the number of elements in the array. The obspec structure is de ned as follows:

uke obspec

struct void fluke type t

g;

typedef

;

f

/* pointer to object ; /* object type

*ob type

struct fluke obspec

*/ */

fluke obspec t;

The region searched must be associated with the same task as the calling thread. On return, if successful, this operation will increment oset by size (to indicate the entire range was searched) and returns the number of objects actually found in count. On the other hand, if the array was too small to accomodate the number of objects found, oset is adjusted to point somewhere after the last object found but before the next object found that wouldn't t in the array, and count is left set to the total number of array elements. The array is lled in with the rst count object descriptions, so the caller doesn't have to rescan the memory already searched. The caller should either make the array larger or consume the object descriptions returned in the array so the array can be used, and then call fluke region search again to search the remaining address range. If any of the pages in the speci ed address range are not currently mapped in the current task's address space, then page faults will occur on those pages, causing them to be faulted in so they can be searched. It is implementation de ned whether these page faults are read faults or write faults. In Fluke implementations that guarantee protection between tasks, any objects found and returned by this routine are guaranteed to be \safe" for the caller to make object invocations on by the time this operation returns. If an object in the memory region was created by a dierent task, and that task performed illegal actions on that object that may have caused the object's state to become invalid (e.g. by overwriting the memory in which the object resides), then fluke region search will either cause the object to be \repaired" enough so that it can be safely accessed again, or else will destroy the object entirely, in which case no indication that the object ever existed will be provided to the caller. The result of a fluke region search call is unde ned if the calling thread is not associated with the same task as the memory region. Parameters

region : The memory region being searched. start : A page aligned start address within the region where the search is to start. end : On entry, must contain the page aligned address within the region where the search is to stop.

On exit, contains the actual address at which the search ended. If on return this is dierent from the requested end address, then the operation should be retried later to search the rest of the memory range. obs : A pointer to the rst element of the array to ll in with the address and type of each Fluke object found. count : On entry, contains the number of available entries in the array. On return, contains the number of entries actually used. 39

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY INVALID RANGE: The speci ed oset or size parameters de ne an invalid range for the region. FLUKE INSANITY NOT CURRENT TASK: The calling thread's task is not the same as the region's task.

40

4.11 uke region set state: set the current state of a region object Synopsis void *task

uke region set state(fluke region t *region, fluke region state *state, fluke ref t ref, fluke ref t *keeper ref);

Description

This operation sets the state of a region object. Parameters

region : The region whose state is to be set. state : If non-null, a pointer to a structure containing the simple (non-reference) state of the region. task ref : If non-null, the address of a task reference object to be copied into the region's task

reference slot. keeper ref : If non-null, the address of a port reference object to be copied into the region's keeper port reference slot.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: region, task ref or keeper ref does not point to an object. FLUKE INSANITY NOT REGION: The object pointed to by region is not a region object. FLUKE INSANITY NOT REF: The object at task ref or keeper ref is not a reference object. FLUKE INSANITY NOT TASK REF: The object at task ref is a reference object, but not a reference to a task. FLUKE INSANITY NOT PORT REF: The object at keeper ref is a reference object, but not a reference to a port. FLUKE INSANITY INVALID OBJECT: The state of an application object has become invalid, e.g. by being overwritten by garbage. FLUKE INSANITY INVALID ADDRESS: The address range speci ed in the uke region state structure does not fall within the allowable task address space. FLUKE INSANITY NOT ALIGNED: The start or size elds of the uke region state structure are not aligned as required by the implementation. Related Information fluke region get state

41

5 Mappings 5.1 Overview

A Fluke mapping object makes a region's memory accessible in a task at a selected address. Mapping objects are the mechanism by which tasks populate their own or other task's address spaces. Given a region reference object, a task may map all or part of the region at a given address with speci ed access permissions. The access permissions associated with a mapping object aect only the task associated with it. Region objects derived from a mapping are not further constrained by the permissions of the mapping, only by the permissions of the region from which the mapping was formed. 10 Fix: This \feature" may be

scrapped. It is inconsistant with the view that, a missing region or mapping should be treated the same as if the region or mapping existed but had FLUKE PROT NONE permissions. In the current implementation, a region without a mapping implies no translations from that point down whereas a region derived from a mapping with FLUKE PROT NONE permission would not be aected by that mapping. The current behaviour is also not intuitive and maybe not all that useful.

Faults caused by threads accessing memory covered by a mapping cause synchronous exceptions to be sent to either the associated region's keeper port (if non-NULL) or the task's keeper port. The portion of a task's address space that can be \mapped" is architecture dependent. For example, some parts of a task's address space may be reserved for kernel uses such as the Fluke entry point area.

5.2 State

The processor architecture-independent portion of a mapping object consists of:

uke mapping state

g;

struct vm offset t vm offset t vm size t fluke prot t fluke ref t

; /* ; /* /* /*

region off start va size prot

; ;

f

oset in the region mapping start VA in task size of region access allowed

*region ref; fluke ref t

*/ */ */ */

*task ref;

region o is the oset in the region at which the mapping starts. The oset may have processor

architecture-speci c alignment constraints. start va and size de ne the extent of the mapping. Both may have processor architecture-speci c alignment constraints. prot de nes the desired access permission for the region. The actual access allowed may be constrained by the region's maximum protection value. region ref is a reference to the region object being mapped. If NULL, the mapping is treated as though its access permissions were zero. Fix: Clarify this. The exception goes either to the thread (if this is a mapping in the thread's task) or to the keeper for the region derived from the mapping. The latter is not obvious. task ref is a reference to the task object into whose address space the region is being mapped. If NULL,

the mapping has no eect. If region o + size exceeds the size of the region, accesses to the excess memory area will cause synchronous exceptions to be sent to the region keeper. 11

5.3 References

A mapping object may reference:  tasks: The task ref reference.  regions: The region ref reference. 10 Rationale: The main reason was so that POSIX mprotect could be implemented as eciently as possible. If changing the permission of a mapping to RO caused all inherited mappings to be likewise modi ed, the cost in TLB ushes might be non-trivial. 11 Rationale: The alternative would be to generate an insanity exception. However, if a region were shrunk after the mapping was created, a spontaneous exception would have to be generated for all mappings over the region.

42

A mapping object cannot be referenced by any object.

43

5.4 uke mapping create: create a new memory mapping

Synopsis

fluke error t

uke mapping create(fluke mapping t *new mapping);

Description

Creates a new empty mapping, with no memory region or task association. In order for the mapping to be useful, it must be associated with a memory region and task address space using fluke mapping set state. Parameters

new mapping : A pointer to the address in the current task's address space at which to create the

new mapping object. There must be no existing Fluke objects at this location; otherwise the results are unde ned.

Errors

If any of the following errors is detected, the appropriate error code is returned: FLUKE NO MEMORY: Insucient kernel resources were available. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new mapping. FLUKE INSANITY NOT ALIGNED: new mapping is not properly aligned for a mapping object. Related Information fluke mapping set state

44

5.5 uke mapping destroy: destroy a memory mapping

Synopsis void

uke mapping destroy(fluke mapping t *mapping);

Description

Destroys a mapping created with fluke mapping create. The memory range de ned by the mapping is no longer accessible. Parameters

mapping : The mapping to destroy. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mapping does not point to an active object. FLUKE INSANITY NOT MAPPING: The object pointed to by mapping is not a mapping object. FLUKE INSANITY INVALID OBJECT: The state of the mapping object has become invalid. Related Information fluke mapping create

45

5.6 uke mapping get state: retrieve the current state of a mapping object

Synopsis

uke mapping get state(fluke mapping t *mapping, [out] fluke mapping state *state, [out] fluke ref t *region ref, [out] fluke ref t *task ref);

void

Description

This operation retrieves the state of a mapping object. Parameters

mapping : The mapping whose state is to be retrieved. state : If non-null, the structure to ll in with the simple (non-reference) mapping state. region ref : If non-null, the address of a reference object to associate with the mapping's region

object. task ref : If non-null, the address of a reference object to associate with the mapping's task object.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mapping does not point to an active object. FLUKE INSANITY NOT MAPPING: The object pointed to by mapping is not a mapping object. FLUKE INSANITY INVALID OBJECT: The state of the mapping object has become invalid. FLUKE INSANITY NOT REF: region ref or task ref is not a pointer to a reference object. Related Information fluke mapping set state

46

5.7 uke mapping move: move a mapping object from one location to another

Synopsis void

uke mapping move(fluke mapping t *old addr, fluke mapping t *new addr);

Description

Moves the speci ed active mapping object from one location in the caller's address space to another. The memory addressed by new addr must not already contain any active Fluke objects. On return, the mapping object will reside at new addr and the memory left behind at old addr will have unde ned contents. Parameters

old addr : The address of the active mapping object to move. new addr : The location in memory to which the mapping is to be moved. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: No object was found at old addr. FLUKE INSANITY NOT MAPPING: The object pointed to by old addr is not a mapping object. FLUKE INSANITY INVALID OBJECT: The state of the mapping object has become invalid. FLUKE INSANITY OBJECT EXISTS: An object already exists at new addr. FLUKE INSANITY NOT ALIGNED: new addr is not properly aligned for a mapping object.

47

5.8 uke mapping protect: change the protection of an address mapping

Synopsis void

uke mapping protect(fluke mapping t *mapping, fluke prot t prot);

Description

Attempts to change the protections of all pages covered by the speci ed mapping in the mapping's associated task. The actual access permission used is the lesser of the provided protection value and the maximum protection value of the associated region. fluke mapping protect aects only the address space of the task associated with the mapping object. Region and mapping objects derived directly or indirectly from the mapping are unaected. Note that this function is semantically equivalent to doing fluke mapping get state, changing the protection eld of the state and then calling fluke mapping set state. Parameters

mapping : The mapping object whose protection is being changed. prot : The permissions desired for the current mapping. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mapping does not point to an active object. FLUKE INSANITY NOT MAPPING: The object pointed to by mapping is not a mapping object. FLUKE INSANITY INVALID OBJECT: The state of the mapping object has become invalid. FLUKE INSANITY INVALID PROT: The requested protection, prot, was invalid. Related Information

,

,

, POSIX.1b mprotect

fluke mapping get state fluke mapping set state fluke region protect

48

5.9 uke mapping set state: set the current state of a mapping object Synopsis

uke mapping set state(fluke mapping t *mapping, fluke mapping state *state, fluke ref t

void *region

ref, fluke ref t *task ref);

Description

This operation sets the state of a mapping object. Parameters

mapping : The mapping whose state is to be set. state : If non-null, a pointer to a structure containing the simple (non-reference) state of the map-

ping.

region ref : If non-null, the address of a region reference object to be copied into the mapping's

region reference slot. task ref : If non-null, the address of a task reference object to be copied into the mapping's task reference slot.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mapping or task ref does not point to an object. FLUKE INSANITY NOT MAPPING: The object pointed to by mapping is not a mapping object. FLUKE INSANITY NOT REF: The object at task ref or region ref is not a reference object. FLUKE INSANITY NOT REGION REF: The object at region ref is a reference object, but not a reference to a region. FLUKE INSANITY NOT TASK REF: The object at task ref is a reference object, but not a reference to a task. FLUKE INSANITY INVALID OBJECT: The state of an application object has become invalid, e.g. by being overwritten by garbage. FLUKE INSANITY INVALID ADDRESS: The address range speci ed in the uke mapping state structure does not fall within the allowable task address space. FLUKE INSANITY NOT ALIGNED: The start or size elds of the uke mapping state structure are not aligned as required by the implementation. FLUKE INSANITY ADDRESS OVERLAP: The address range speci ed in the uke mapping state structure overlaps with the address range of an existing mapping. Related Information fluke mapping get state

49

6 Ports

6.1 Overview

This section describes the Fluke API operations related to port objects.

6.2 State

The processor architecture-independent portion of a port object consists of:

uke port state

g;

struct integer t

fluke ref t

f

; /* Alias value to pass back to the server

alias

*/

*pset ref;

alias holds the value to pass back to the server when it receives an IPC invocation through this port,

allowing the server to distinguish requests to dierent ports that are attached to a single port set. The (arbitrary, optional) alias value is normally set by the server. pset ref is a reference to the port set object that this port is associated with. If NULL, the port is not part of a port set and service threads cannot rendezvous with clients using the port.

6.3 References

A port object may reference:  port sets: The pset ref reference. A port object may be referenced by:  threads: The thread object scheduler ref or waiting for ref references.  tasks: The task object keeper ref reference.  regions: The region object keeper ref reference.  references: Standalone references used as IPC capabilities.

50

6.4 uke port create: create a new port

Synopsis

fluke error t

uke port create(fluke port t *new port);

Description

Creates a new port object. Until the port is associated with a port set via fluke port set state, no messages can be received on it. Parameters

new port : A pointer to the address in the current task's address space at which to create the new

port object.

Errors

If any of the following errors is detected, the appropriate error code is returned: FLUKE NO MEMORY: Insucient kernel resources were available. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new port. FLUKE INSANITY NOT ALIGNED: new port is not properly aligned for a port object. Related Information

,

fluke port destroy fluke port set state

51

6.5 uke port destroy: destroy a port

Synopsis void

uke port destroy(fluke port t *port);

Description

Destroys an active port created with fluke port create. All outstanding references to the port become invalid. All pending and future IPC operations targeting the port will return FLUKE INVALID DEST. Parameters

port : The port to destroy. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: port does not point to an active object. FLUKE INSANITY NOT PORT: The object pointed to by port is not a port object. FLUKE INSANITY INVALID OBJECT: The state of the port object has become invalid. Related Information fluke port create

52

6.6 uke port get state: retrieve the current state of a port Synopsis void *pset

uke port get state(fluke port t *port, [out] fluke port state *state, [out] fluke ref t ref);

Description

This operation retrieves the application-visible state of a port. The port itself is unaected by the operation. Parameters

port : The port whose state is to be retrieved. state : If non-null, the structure to ll in with the simple (non-reference) region state. pset ref : If non-null, the address of a reference object to associate with the mapping's port set

object.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: port does not point to an active object. FLUKE INSANITY NOT PORT: The object pointed to by port is not a port object. FLUKE INSANITY INVALID OBJECT: The state of the port object has become invalid. FLUKE INSANITY NOT REF: pset ref is not a pointer to a reference object. Related Information fluke port set state

53

6.7 uke port move: move a port object from one location to another

Synopsis void

uke port move(fluke port t *old addr, fluke port t *new addr);

Description

Moves the speci ed active port object from one location in the caller's address space to another. The memory addressed by new addr must not already contain any active Fluke objects. On return, the port object will reside at new addr and the memory left behind at old addr will have unde ned contents. Parameters

old addr : The address of the port object to move. new addr : The location in memory to which the port is to be moved. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: old addr does not point to an active object. FLUKE INSANITY NOT PORT: The object pointed to by old addr is not a port object. FLUKE INSANITY INVALID OBJECT: The state of the port object has become invalid. FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new addr. FLUKE INSANITY NOT ALIGNED: new addr is not properly aligned for a port object.

54

6.8 uke port reference: associates a reference with a port Synopsis void

uke port reference(fluke port t *port, fluke ref t *new port ref);

Description

This function associates an active reference object with the speci ed active port object. The resulting reference can be used in IPC operations and for insertion into port reference slots of various other objects (e.g., threads). Parameters

port : The port object to which the new reference will refer. new port ref : A pointer to a valid reference object. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: port or new port ref does not point to an active object. FLUKE INSANITY NOT PORT: The object pointed to by port is not a port object. FLUKE INSANITY INVALID OBJECT: The state of the port object has become invalid. FLUKE INSANITY NOT REF: new port ref does not point to a valid reference object.

55

6.9 uke port set state: set the current state of a port object Synopsis void

uke port set state(fluke port t *port, fluke port state *state, fluke ref t *pset ref);

Description

This operation can be used to set the application-visible state of a port. Parameters

port : The port whose state is to be modi ed. state : If non-null, a pointer to a structure containing the simple (non-reference) state of the port. pset ref : If non-null, the address of a port set reference object to be copied into the port's port set

reference slot.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: port does not point to an active object. FLUKE INSANITY NOT PORT: The object pointed to by port is not a port object. FLUKE INSANITY INVALID OBJECT: The provided port state contains invalid information. FLUKE INSANITY NOT REF: The object at pset ref is not a reference object. FLUKE INSANITY NOT PSET REF: The object at pset ref is a reference object, but not a reference to a port set. Related Information fluke port get state

56

7 Port Sets 7.1 Overview

This section describes the Fluke API operations related to port set objects. Port sets are a rendezvous point for ports and threads. A port must have an associated port set in order for a thread to receive messages via fluke ipc wait. Multiple ports can be associated with the same port set allowing a pool of threads to service requests from a group of related ports. Ports may be moved between port sets transparently to any clients using the ports.

7.2 State

Port set objects contain no saveable state.

7.3 References

A port set object does not reference any other object. A port set object may be referenced by:  threads: The thread object waiting for ref reference.  ports: The port object pset ref reference.

57

7.4 uke pset create: create a new port set Synopsis

fluke error t

uke pset create(fluke pset t *new pset);

Description

Creates a new port set object. Parameters

new pset : A pointer to the address in the current task's address space at which to create the new

port set object.

Errors

If any of the following errors is detected, the appropriate error code is returned: FLUKE NO MEMORY: Insucient kernel resources were available. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new pset. FLUKE INSANITY NOT ALIGNED: new pset is not properly aligned for a port set object. Related Information fluke pset destroy

58

7.5 uke pset destroy: destroy a port set Synopsis void

uke pset destroy(fluke pset t *pset);

Description

Destroys an active port set created with fluke pset create. All associated ports can no longer be received from; i.e. threads sending on those ports will block. Parameters

pset : The port set to destroy. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: pset does not point to an active object. FLUKE INSANITY NOT PSET: The object pointed to by pset is not a port set object. FLUKE INSANITY INVALID OBJECT: The state of the pset object has become invalid. Related Information fluke pset create

59

7.6 uke pset move: move a port set object from one location to another Synopsis void

uke pset move(fluke pset t *old addr, fluke pset t *new addr);

Description

Moves the speci ed active port set object from one location in the caller's address space to another. The memory addressed by new addr must not already contain any active Fluke objects. On return, the port set object will reside at new addr and the memory left behind at old addr will have unde ned contents. Parameters

old addr : The address of the port set object to move. new addr : The location in memory to which the port set is to be moved. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: old addr does not point to an active object. FLUKE INSANITY NOT PSET: The object pointed to by old addr is not a port set object. FLUKE INSANITY INVALID OBJECT: The state of the port set object has become invalid. FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new addr. FLUKE INSANITY NOT ALIGNED: new addr is not properly aligned for a port set object.

60

7.7 uke pset reference: associates a reference with a port set Synopsis void

uke pset reference(fluke pset t *pset, fluke ref t *new pset ref);

Description

This function associates an active reference object with the speci ed active port set object. The resulting reference can be used for insertion into port set reference slots of various other objects. Parameters

pset : The port set object to which the new reference will refer. new pset ref : A pointer to a valid reference object. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: pset or new pset ref does not point to an active object. FLUKE INSANITY NOT PORT: The object pointed to by pset is not a port set object. FLUKE INSANITY INVALID OBJECT: The state of the port set object has become invalid. FLUKE INSANITY NOT REF: new pset ref does not point to a valid reference object.

61

8 Interprocess Communication 8.1 Overview

This section describes the Fluke API operations provided for interprocess communication (IPC). Although all of these functions operate on various types of Fluke objects (there is no single \Fluke IPC object type"), they are closely related in function and therefore are described together anyway. Note that the functions described here are high-level functions callable by C and other languages; they do not necessarily represent the actual Fluke API entrypoints, but may instead be stubs that in turn invoke the actual entrypoints. In some cases, much better application-level performance can be achieved by calling the Fluke API entrypoints directly using architecture-speci c calling conventions; for example, this allows application code to make full use of registerized messages and such.

8.2 IPC parameters

All Fluke IPC calls that cause data to be transferred take as a parameter a pointer to a parameter structure of type fluke ipc params t. The exact de nition and layout of this structure is processor architecture-speci c; however, the structure is guaranteed to have at least the following elds:

uke ipc params

g;

struct fluke ipc fluke ipc fluke ipc fluke ref fluke ipc fluke ipc fluke ipc fluke ipc fluke ref fluke ipc

buf buf buf t ref buf buf buf t ref

t t count t count t t t count t count t

f

;

send buf *send buf tab send buf count **send ref tab send ref count recv buf *recv buf tab recv buf count **recv ref tab recv ref count

;

;

;

; ; ; ; ; ;

/* /* /* /* /* /* /* /* /* /*

rst data buer to send additional data buers to send number of additional buers references to send number of references to send rst data buer to receive into additional data buers to receive number of additional buers references to receive into number of references to receive

*/ */ */ */ */ */ */ */ */ */

The send * elds in the parameters structure describe data and references to send in a sending operation; these elds are ignored by operations that only receive. Similarly, the recv * elds describe data buers and references into which to receive incoming messages; these elds are ignored by operations that only send.

8.2.1 IPC buer descriptors

Speci c data buers to send from or receive into are speci ed using structures of type fluke ipc buf t, which contains at least the following elds:

uke ipc buf

g;

struct natural t void

f

; /* size of buer in IPC words ; /* pointer to beginning of buer

words *buf

*/ */

The words eld speci es the length of the data buer in IPC words, and the buf eld contains a pointer to the actual data buer.

8.2.2 Send parameters

The send buf eld describes the rst buer of simple data to send. In sending operations that logically begin a message (call, connect send or ack send, etc.), this rst simple data buer must always be present, and send buf.words must be at least FLUKE MIN MSG WORDS. In sending operations that don't begin a message (i.e. a \plain" send), the word count can be any nonnegative number, including zero. The send buf tab eld is meaningful only if send buf count is nonzero, and points to an array of fluke ipc buf structures describing additional simple data buers to be sent. The send buf count is the number of entries in this array. The word count in any of these buer descriptions can be zero; in that case, that buer entry is skipped and causes no data to be sent. 62

The send ref tab eld points to an array of pointers to Fluke reference objects containing references to be passed. The number of references to be sent in this way is indicated by send ref count. If send ref count is nonzero, then all of the reference pointers in the array must be valid and point to active reference objects; null pointers are not allowed in this array. (However, pointers to null references may be present in the array, in which case the null reference is passed to the receiver.) The send parameter elds in the fluke ipc params structure are not modi ed during any Fluke IPC operation.

8.2.3 Receive parameters

The receive-related elds work exactly the same way as the send elds, except they are used for receive operations instead of send operations. However, unlike send operations which always send all of the data and references specify unless the IPC connection is abnormaly broken for some reason, receive operations only ll the receive buers and references with as much data and references as the sender sent. Thus, when a receive operation completes, the Fluke implementation must indicate to the application how many data words and references were actually received. It does this by adjusting the recv buf.words, recv buf count, and recv ref count elds of the IPC parameter structure before returning. On return from a receiving IPC operation, the recv buf count is decreased by the number of data buers that were completely lled with receive data, starting with the rst buer (the buer speci ed by the caller in recv buf). The recv buf.words eld indicates the number of data words remaining in the rst receive buer that was not completely lled. The recv ref count, on return from the IPC operation, is decreased by the number of references that were received; it indicates the number of unreceived references remaining in the recv ref tab provided. On return from a receiving IPC operation, all of the receive parameter elds other than the ones describe above may have been modi ed, and are left with unde ned contents. However, no receive parameter elds will be modi ed (or used at all) in IPC operations that don't involve receiving anything. Furthermore, although the contents of the parameter structure may be modi ed, any receive buer table or receive reference pointer table provided (pointed to by recv buf tab and recv ref tab, respectively) will not be modi ed by the IPC operation, although of course the buers and references they refer to will be modi ed.

63

8.3 uke ipc call: make a synchronous idempotent call to a port Synopsis

vm size t

uke ipc call(fluke ref t *destination, [out] fluke ipc params t *params);

Description

This operation makes a synchronous IPC invocation to the port referred to by the destination port reference. A message is sent to the server, and the client thread waits until a reply is received or an error is detected. The request may be delivered to the server multiple times due to message retransmission and other temporary conditions. If the request is serviced multiple times, and the server replies to each request, which reply the client actually receives is unde ned. There are no guarantees about message ordering. In some Fluke implementations it is possible for messages to arrive at the server in a dierent order from which they were sent. In addition to the destination and message to send, the client must specify a buer to receive the reply into. Up to receive msg max size bytes of reply data will be received; any additional reply data the server sends back will be silently discarded. There may be architecture-speci c restrictions on buer alignment, and padding may be added to request and reply messages in transit. If the Fluke implementation detects an error during message transmission, it will return a reply message to the client containing an error code in the rst word possibly followed by some data describing the error in more detail. Note that an error reply message send by the Fluke implementation is indistinguishable from an error reply from a server or an intermediary interposed on the IPC connection. Parameters

destination : A pointer to a port reference indicating the port to invoke. send msg buf : A pointer to the request message to send. Some architectures may require word

alignment.

send msg size : Size of the message to send. receive msg buf : A pointer to the reply message to send. Some architectures may require word

alignment.

receive msg max size : Maximumsize of the reply message to receive. Must be at least FLUKE MIN MSG SIZE,

which is an architecture-speci c constant. Any additional reply message data beyond this size will be silently discarded. Some architectures may require this size to be a multiple of the machine word size.

Returns

Returns the size of the reply message actually received. Note that some padding may have been added to the reply message, so the client must be prepared to ignore extra data in the reply. Errors

If any of the following errors is detected, a reply is generated with the appropriate error code in the rst word of the reply: FLUKE INVALID DEST: The IPC target referenced by destination is invalid, e.g. because the port it refers to was destroyed or the server task was terminated. FLUKE MESSAGE TOO LARGE: The request or reply message is too large for the communication channel over which it is being sent. The channel's actual maximum message size is provided in the second word of the reply. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: No active object was found at destination. 64

: The object at destination is not a reference object. FLUKE INSANITY NOT PORT REF: The object at destination is a reference object, but not a reference to a port. FLUKE INSANITY INVALID OBJECT: The state of the object at destination is invalid, e.g. by being overwritten by garbage. FLUKE INSANITY BUFFER TOO SMALL: A receive buer smaller than FLUKE MIN MSG SIZE was supplied. FLUKE INSANITY NOT REF

Related Information

,

fluke ipc wait fluke ipc reply

65

8.4 uke ipc client connect send: create a reliable connection to a server Synopsis

fluke error t *ipc params

);

uke ipc client connect send(fluke ref t *destination, fluke ipc params t

Description

This function initiates a reliable IPC connection with the server controlling the port referred to by the destination port reference. If successful, a server thread will be found and attached to the current (client) thread. The client can then commence communication using the fluke ipc client op family of operations. Initially the client is the sender and the server is the receiver. Upon successfully establishing a connection, the data and/or references described by the send parameter elds in ipc params are immediately sent to the server as the rst part of the client's message. The number of words in the rst data buer to send, ipc params->send buf.words, must be at least FLUKE MIN MSG SIZE; it is impossible to establish a connection without transferring this minimum amount of data at the same time. However, note that this minimum message size restriction only applies at the time of connection establishment; subsequent fluke ipc client send calls accept buers of any size, subject to any alignment restrictions the architecture may impose. Furthermore, there are no minimums imposed on references being sent. If the current thread is already connected to a server when this call is made, the existing connection is broken as if by fluke ipc client disconnect. Parameters

destination : A pointer to a port reference indicating the port to invoke. ipc params : A pointer to a structure describing data and references to send. Only the send param-

eter elds in this structure are used; the receive parameter elds are ignored. All elds remain unmodi ed by the call.

Returns

Returns one of the following codes: FLUKE SUCCESS if the connection succeeded or one of the following return codes on failure: FLUKE SUCCESS: The connection has been established, and all data indicatied by the send parameters in ipc params has been sent (though not necessarily delivered yet to the receiver). FLUKE IPC CONNECT INVALID DEST: The IPC target referenced by destination is invalid, e.g. because the port it refers to was destroyed or the server task was terminated. Note that if the IPC destination is invalid, it is unspeci ed whether this condition will be detected at connection time by this function, or at a later stage such as the rst send or receive. Application code must in general be prepared to handle error conditions detected at any time during communication.12 FLUKE IPC SEND DISCONNECTED: The connection was successfully established, but it was broken while sending the data and references speci ed. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: No active object was found at destination. FLUKE INSANITY NOT REF: The object at destination is not a reference object. 12 Rationale: A client-side network proxy should not have to check whether or not the server is still alive before accepting a connection on a port, as that would involve an extra unnecessary message.

66

: The object at destination is a reference object, but not a reference

FLUKE INSANITY NOT PORT REF

to a port.

: The state of the object at destination is invalid, e.g. by being

FLUKE INSANITY INVALID OBJECT

overwritten by garbage.

: The supplied initial message was smaller than FLUKE MIN MSG SIZE. FLUKE INSANITY BUFFER UNALIGNED: A message buer was not aligned properly according to the architecture-speci c requirements.

FLUKE INSANITY BUFFER TOO SMALL

Related Information

,

,

,

,

fluke ipc side send fluke ipc side receive fluke ipc side over fluke ipc side disconnect fluke ipc wait

67

8.5 uke ipc client connect send over receive: perform a reliable RPC to a server Synopsis

uke ipc client connect send over receive(fluke ref t *destination,

fluke error t fluke ipc params t *ipc

params);

Description

This function is a combination of fluke ipc connect send and fluke ipc over receive. It establishes a reliable IPC connection with a server thread, sends some data and/or references to the server, then reverses the connection and waits to receive data from the server. Parameters

destination : A pointer to a port reference indicating the port to invoke. ipc params : A pointer to a structure describing data and references to send, and the buers and

references to receive the response into. Only the receive parameter elds are modi ed by the call.

Returns

Returns one of the following codes: FLUKE SUCCESS if the connection succeeded or one of the following return codes on failure: FLUKE SUCCESS: The connection has been established, and all data indicatied by the send parameters in ipc params has been sent (though not necessarily delivered yet to the receiver). FLUKE IPC CONNECT INVALID DEST: The IPC target referenced by destination is invalid, e.g. because the port it refers to was destroyed or the server task was terminated. FLUKE IPC SEND DISCONNECTED: The connection was successfully established, but it was broken while sending the data and references speci ed. FLUKE OVER DISCONNECTED: The IPC connection was established, but was broken while trying to reverse the connection. FLUKE IPC RECV MORE DATA: A reliable IPC connection was established, but all of the client's receive data buers lled up before the client nished sending its rst message. The server must make more room for incoming data and call fluke ipc server receive to receive it. The ipc params structure is updated appropriately to indicate the number of references received. FLUKE IPC RECV MORE REFS: A reliable IPC connection was established, but all of the client's receive references were lled before the client nished sending its rst message. The server must make room for more references and call fluke ipc server receive to receive it. The ipc params structure is updated appropriately to indicate the amount of data received. FLUKE IPC RECV DISCONNECTED: A reliable IPC connection was established, but the sender disconnected afterwards after sending some data but before the receiver's receive buers lled up. The ipc params structure is updated appropriately to indicate the amount of data and references received. FLUKE IPC WAIT ONEWAY: A one-way message was received into its receive buer(s). The server merely needs to process the message and then wait for more messages on the port set if appropriate; no response of any kind is required. FLUKE IPC WAIT IDEMPOTENT: An idempotent request was received into its message buer(s). The server should process the message and then reply to it using fluke ipc reply. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: 68

: No active object was found at destination. FLUKE INSANITY NOT REF: The object at destination is not a reference object. FLUKE INSANITY NOT PORT REF: The object at destination is a reference object, but not a reference to a port. FLUKE INSANITY INVALID OBJECT: The state of the object at destination is invalid, e.g. by being overwritten by garbage. FLUKE INSANITY BUFFER TOO SMALL: The supplied initial message was smaller than FLUKE MIN MSG SIZE. FLUKE INSANITY BUFFER UNALIGNED: A message buer was not aligned properly according to the architecture-speci c requirements. FLUKE INSANITY NO OBJECT

Related Information

,

,

,

,

fluke ipc side send fluke ipc side receive fluke ipc side over fluke ipc side disconnect fluke ipc wait

69

8.6 uke ipc reply: reply to an idempotent call Synopsis void

uke ipc reply( void *reply msg buf, vm size t reply msg size);

Description

This operation completes an idempotent IPC invocation by returning the reply. The destination of the reply is implied by the outstanding request which the replying thread is servicing. A reply message may be dropped with no noti cation to the server. In this case the request message will eventually be resent, reserviced and a new reply sent. If the reply message supplied is larger than the client's receive buer, the excess is silently discarded. Calls to fluke ipc reply when not in the context of an fluke ipc call are silently ignored. Parameters

reply msg buf : A pointer to the reply message to send. Some architectures may require word

alignment. reply msg size : Size of the message to send. The message may be truncated if this size exceeds the client's provided message receive buer size. Related Information fluke ipc call

70

8.7 uke ipc send: send a one-way message to a port Synopsis

fluke error t

uke ipc send(fluke ref t *destination, void *msg buf, vm size t msg size);

Description

This function sends a one-way message to the port referred to by the destination port reference. The message transmission will have at-most-once semantics: it may or may not arrive at its destination, but if it does arrive, it will be seen by the server only once, and its contents will be uncorrupted by network bit errors and such. (Whether a message is subject to being modi ed maliciously depends on the security policies of the Fluke implementation and the surrounding environment.) There are no guarantees about message ordering. In some Fluke implementations it is possible for messages to arrive at the server in a dierent order from which they were sent. There may be architecturespeci c restrictions on buer alignment, and padding may be added to request and reply messages in transit. If an error occurs during message transmission, it may or may not be detected by the Fluke implementation. If an error is detected, an appropriate error code may be returned. Otherwise, this function returns FLUKE SUCCESS, and the message may or may not reach its destination. Thus, the application should only use the return code as a hint, and must still be prepared to tolerate arbitrary message loss. Parameters

destination : A pointer to a port reference indicating the port to send the message to. msg buf : A pointer to the message to send. Some architectures may require word alignment. msg size : Size of the message to send. Errors

If any of the following errors is detected, it is indicated in the function's return value: FLUKE INVALID DEST: The IPC target referenced by destination is invalid, e.g. because the port it refers to was destroyed or the server task was terminated. FLUKE MESSAGE TOO LARGE: The message to be sent is too large for the communication channel over which it is being sent. The application must use a synchronous idempotent IPC to determine the actual maximum message size of the channel, then try sending a smaller message. The maximum message of a channel may change at any time. Note once again that messages may be dropped in transit because they are too large without notifying the sender with this error code; if the sender keeps retransmitting the same message, it may consistently be dropped in this way. Thus, the sending application should also (re-)check the maximum message size using an idempotent IPC if it experiences consistent message loss. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: No active object was found at destination. FLUKE INSANITY NOT REF: The object at destination is not a reference object. FLUKE INSANITY NOT PORT REF: The object at destination is a reference object, but not a reference to a port. FLUKE INSANITY INVALID OBJECT: The state of the object at destination is invalid, e.g. by being overwritten by garbage. Related Information

,

fluke ipc wait fluke ipc call

71

8.8 uke ipc setup wait receive: set up a server thread and wait for incoming IPC invocations

Synopsis

uke ipc setup wait receive( uke pset t *pset, [in/out] fluke ipc params t

fluke ipc error t *ipc params void **port

, [out]

alias);

Description

This function initializes a thread's server-side IPC state, including the port set the server thread is attached to, and then puts the server thread to sleep waiting for an incoming IPC request on that port set. Later, the thread can wait for subsequent messages on the same port set using fluke ipc wait receive or one of the combination operations that includes a wait receive. Parameters

pset : The port set on which the server thread should wait for incoming IPC invocations. ipc params : A pointer to a structure describing data buers and reference objects to receive infor-

mation into. Only the receive parameter elds in this structure are used; the send parameter elds are ignored. port alias : When an incoming IPC request is successfully received, this pointer is set to the port alias attached to the port through which the IPC invocation was made, allowing the server to distinguish requests to dierent ports that are attached to a single port set. Returns

This function returns a status code providing information about the received IPC invocation. (The return codes are the same for fluke ipc wait receive and fluke ipc setup wait receive.) FLUKE SUCCESS: A reliable IPC connection was established, and the entire initial message from the client was received into the the server's receive buers and references. The ipc params structure is updated appropriately to indicate the amount of data and references received. FLUKE IPC RECV MORE DATA: A reliable IPC connection was established, but all of the receiver's data buers lled up before the client nished sending its rst message. The server must make more room for incoming data and call fluke ipc server receive to receive it. The ipc params structure is updated appropriately to indicate the number of references received. FLUKE IPC RECV MORE REFS: A reliable IPC connection was established, but all of the receiver's references were lled before the client nished sending its rst message. The server must make room for more references and call fluke ipc server receive to receive it. The ipc params structure is updated appropriately to indicate the amount of data received. FLUKE IPC RECV DISCONNECTED: A reliable IPC connection was established, but the sender disconnected afterwards after sending some data but before the receiver's receive buers lled up. The ipc params structure is updated appropriately to indicate the amount of data and references received. FLUKE IPC WAIT ONEWAY: A one-way message was received into its receive buer(s). The server merely needs to process the message and then wait for more messages on the port set if appropriate; no response of any kind is required. FLUKE IPC WAIT IDEMPOTENT: An idempotent request was received into its message buer(s). The server should process the message and then reply to it using fluke ipc reply. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: No active object was found at pset. 72

: The object pointed to by pset is not a port set object. FLUKE INSANITY INVALID OBJECT: The state of the object at pset is invalid, e.g. due to being overwritten by garbage. FLUKE INSANITY NOT PSET

Related Information fluke ipc wait receive

73

8.9 uke ipc side alert: send an interrupt on a reliable IPC connection

Synopsis

fluke error t

uke ipc side alert(void);

Description

This call allows either side of a reliable IPC connection to send a software interrupt to the other side. The eect is as if one side performed a fluke thread interrupt on the thread object for the other side. XXX this is wrong. Related Information fluke thread interrupt

74

8.10 uke ipc side disconnect: destroy a reliable IPC connection

Synopsis void

uke ipc side disconnect(void);

Description

This call allows either side of a reliable IPC connection to break that connection. After a disconnect, any further invocations on the channel will fail with a FLUKE op DISCONNECTED return code. If the sender disconnects while the receiver is blocked in a fluke ipc side receive operation, the receive operation terminates with a FLUKE RECV DISCONNECTED return code. The IPC parameter structure used in the receive operation will re ect any partial transfer of data or references. This is the normal way for a conversation to be terminated: the sender disconnects after sending all relevant message data, and the receiver is noti ed of the disconnection after it has received all the data. No information is lost when the sender disconnects in this way. On the other hand, if the current receiver disconnects, this is considered abnormal termination of the connection, and data may be lost. If the sender keeps sending data on the connection, it will be noti ed of the disconnection eventually with a FLUKE SEND DISCONNECTED error code, but there is no guarantee of how soon this will occur, or how much information may be lost before it does. If the sender tries to reverse (\over") the connection, then it will receive a FLUKE OVER DISCONNECTED error return without any data being received. If the sender eventually disconnects instead of reversing the connection, then it may never be noti ed that the connection was broken prematurely. Related Information

,

,

,

fluke ipc connect fluke ipc side send fluke ipc side receive fluke ipc side over receive

75

8.11 uke ipc side over receive: reverse the transfer direction of a reliable IPC connection

Synopsis

fluke error t

uke ipc side over receive([in/out] fluke ipc params t *ipc params);

Description

This function allows the current sender on a reliable IPC connection to switch roles and become the receiver. If the current receiver is waiting for data in an fluke ipc side receive operation, its receive operation will immediately return FLUKE SUCCESS, indicating that all information in that message has been received and the sender is ready to reverse the connection. The receiver must then perform an ack send operation in order to complete the connection reversal and begin transferring information in the other direction. If the receiver was already waiting in an ack send operation, the reversal takes place immediately. Parameters

ipc params : A pointer to a structure describing data buers and reference objects to receive infor-

mation into. Only the receive parameter elds in this structure are used; the send parameter elds are ignored.

Returns

Returns one of the following codes: FLUKE SUCCESS: The connection reversal has succeeded and the entire message subsequently sent by the other side was received into the initial receive buers and references provided to this operation. The other side is now ready to reverse the connection again. FLUKE OVER DISCONNECTED: The IPC connection does not exist, or was broken unexpectedly for some reason before the connection reversal actually took place, e.g. because the other side disconnected or was terminated. FLUKE RECV DISCONNECTED: The connection was reversed successfully, but the sender disconnected afterwards before the receiver's receive buers lled up. The ipc params structure is updated appropriately to indicate the amount of data and references received. This return code often indicates normal connection termination. FLUKE RECV MORE DATA: All of the receiver's data buers lled up but there may still be more simple data to receive. The receiver must make more room for incoming data and call fluke ipc side receive to receive them. FLUKE RECV MORE REFS: recv ref count references have been received, but there may still be more coming; the receiver must make room for more references and call fluke ipc side receive to receive them. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NOT SENDER: The current thread is not the sender on the speci ed IPC connection. FLUKE INSANITY NO OBJECT: One of the pointers in the recv ref tab array points to an area of memory not containing any object. FLUKE INSANITY NOT REF: The object pointed to by one of the recv ref tab pointers is not a reference object. FLUKE INSANITY INVALID OBJECT: The state of an object has become invalid, e.g. by being overwritten by garbage. 76

Related Information

,

,

,

fluke ipc client connect send fluke ipc side disconnect fluke ipc side send fluke ipc side receive

77

8.12 uke ipc side receive: receive data through reliable IPC Synopsis

fluke error t

uke ipc side receive([in/out] fluke ipc params t *ipc params);

Description

This function receives data words and references across one of the current thread's reliable IPC connections. A client thread uses fluke ipc client receive to receive data from its server, while a server thread uses fluke ipc server receive to receive data from its current client. The calling thread receives data, waiting if necessary, until the supplied buer for at least one of the data types (simple data or references) becomes full or until the sender reverses or breaks the connection. If all of the data buers or all of the references are lled, then this function returns and the receiver must create more room and then make another call to this function to continue receiving. After the receive buer for one data type lls up, the receiver may or may not be able to continue receiving data of the other type before emptying the full receive buer. In other words, Fluke implementations (and any intermediaries interposed on the IPC channel) may treat the two data types as independent parallel streams, or they may impose some relative ordering between the streams. Thus, for example, a receiver can't expect to be able to receive all the items of one data type, followed by all the items of another in a separate \phase"; the receiver must accept whatever is sent, when it is sent, if it is to receive at all. By implication, if the receiver provides one or more data buers but no reference objects to receive into, or one or more reference objects but no data buers, then this call may return immediately without transferring anything if the sender is trying to send one or more instances of the data type for which the receiver did not supply a receive buer. The receiver must create an appropriate buer and reinvoke the receive operation in order to receive further data of either type. For references, the provided receive reference table must contain pointers to valid reference objects created with fluke ref create. The existing reference objects will be modi ed to be equivalent to the corresponding references sent by the sender. The reference objects themselves are not transferred; their contents is merely copied from the sender's reference object to the receiver's. Parameters

ipc params : A pointer to a structure describing data buers and reference objects to receive infor-

mation into. Only the receive parameter elds in this structure are used; the send parameter elds are ignored.

Returns

Returns one of the following codes: FLUKE SUCCESS: The sender has nished sending message data and is attempting to reverse the transfer direction. The other side is now ready to reverse the connection again. The caller (receiver) must perform an ack send operation to complete the reversal and initiate data transfer in the other direction. FLUKE IPC RECV DISCONNECTED: The connection was reversed successfully, but the sender disconnected afterwards before the receiver's receive buers lled up. The ipc params structure is updated appropriately to indicate the amount of data and references received. This return code often indicates normal connection termination. FLUKE IPC RECV MORE DATA: All of the receiver's data buers lled up but there may still be more simple data to receive. The receiver must make more room for incoming data and call this function again. FLUKE IPC RECV MORE REFS: recv ref count references have been received, but there may still be more coming; the receiver must make room for more references and call this function again. 78

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NOT RECEIVER: The current thread is not the receiver on the speci ed IPC connection. FLUKE INSANITY NO OBJECT: One of the pointers in the recv ref tab array points to an area of memory not containing any object. FLUKE INSANITY NOT REF: The object pointed to by one of the recv ref tab pointers is not a reference object. FLUKE INSANITY INVALID OBJECT: The state of an object has become invalid, e.g. by being overwritten by garbage. Related Information

,

,

,

fluke ipc client connect send fluke ipc side send fluke ipc side over receive fluke ipc side disconnect

79

8.13 uke ipc side send: send data across a reliable IPC connection

Synopsis

fluke error t

uke ipc side send(fluke ipc params t *ipc params);

Description

This function sends the speci ed data words and references across one of the current thread's reliable IPC connections. A client thread uses fluke ipc client send to send data to its server, while a server thread uses fluke ipc server send to send data back to its client. Parameters

ipc params : A pointer to a structure describing data and references to send. Only the send param-

eter elds in this structure are used; the receive parameter elds are ignored. All elds remain unmodi ed.

Returns

Returns one of the following codes: FLUKE SUCCESS: All of the speci ed data was sent successfully. (Note that this does not necessarily mean that it has already been delivered to the nal receiver.) FLUKE IPC SEND DISCONNECTED: The IPC connection on which the transfer is to take place does not exist, or has been broken for some reason, such as by the receiver being terminated. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NOT SENDER: The current thread is not the receiver on the speci ed IPC connection. FLUKE INSANITY NO OBJECT: One of the pointers in the send ref tab array points to an area of memory not containing any object. FLUKE INSANITY NOT REF: The object pointed to by one of the send ref tab pointers is not a reference object. FLUKE INSANITY INVALID OBJECT: The state of an object has become invalid, e.g. by being overwritten by garbage. Related Information

,

,

,

fluke ipc client connect send fluke ipc side receive fluke ipc side over receive fluke ipc side disconne

80

8.14 uke ipc wait receive: wait on a port set for incoming IPC invocations Synopsis

fluke ipc error t void **port alias

);

uke ipc wait receive([in/out] fluke ipc params t *ipc params, [out]

Description

This function causes the current thread to wait for and receive incoming IPCs on a port set. A message of any avor (one-way, idempotent, reliable) may be received using this function. The port set to receive from must have already been set up through a previous call to fluke ipc setup wait receive. The caller must provide one or more message buers into which to receive the incoming message. For one-way and idempotent IPC, the entire incoming message will be copied into the buer before this function returns and the server thread receives control again. If the receive buer is too small for the incoming message, then the message will be silently truncated. For reliable IPC invocations, the rst part of the incoming message is received into the provided receive buers and references; however, if all of the data and references to be received do not t in the initial buers provided, then the fluke ipc wait receive operation will return, and the server must prepare more receive buers or references and call fluke ipc server receive one or more times to receive the remainder of the incoming message. If the current thread is already connected to a client when this call is made, the existing connection is broken as if by fluke ipc server disconnect before the server thread goes to sleep waiting for a new connection. Parameters

ipc params : A pointer to a structure describing data buers and reference objects to receive infor-

mation into. Only the receive parameter elds in this structure are used; the send parameter elds are ignored. port alias : When an incoming IPC request is successfully received, this pointer is set to the port alias attached to the port through which the IPC invocation was made, allowing the server to distinguish requests to dierent ports that are attached to a single port set.

Returns

When the wait operation completes, either control will be returned to the point in the application immediately after the call to fluke ipc wait receive, as if a normal function return was performed, or control will be returned to the point in the application immediately ofter the call to fluke ipc setup wait receive that was used to set up the server thread to receive IPC requests, as if a longjmp had been performed to that point. If this behavior is undesirable, the application may simply use fluke ipc setup wait receive every time the server thread needs to wait for a message; however, there is likely to be some performance penalty for doing this, depending on the Fluke implementation. This function returns a status code providing information about the received invocation. (The return codes are the same for fluke ipc wait receive and fluke ipc setup wait receive.) FLUKE SUCCESS: A reliable IPC connection was established, and the entire initial message from the client was received into the the server's receive buers and references. The ipc params structure is updated appropriately to indicate the amount of data and references received. FLUKE IPC RECV MORE DATA: A reliable IPC connection was established, but all of the receiver's data buers lled up before the client nished sending its rst message. The server must make more room for incoming data and call fluke ipc server receive to receive it. The ipc params structure is updated appropriately to indicate the number of references received. FLUKE IPC RECV MORE REFS: A reliable IPC connection was established, but all of the receiver's references were lled before the client nished sending its rst message. The server must make 81

room for more references and call fluke ipc server receive to receive it. The ipc params structure is updated appropriately to indicate the amount of data received. FLUKE IPC RECV DISCONNECTED: A reliable IPC connection was established, but the sender disconnected afterwards after sending some data but before the receiver's receive buers lled up. The ipc params structure is updated appropriately to indicate the amount of data and references received. FLUKE IPC WAIT ONEWAY: A one-way message was received into its receive buer(s). The server merely needs to process the message and then wait for more messages on the port set if appropriate; no response of any kind is required. FLUKE IPC WAIT IDEMPOTENT: An idempotent request was received into its message buer(s). The server should process the message and then reply to it using fluke ipc reply. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: No active object was found at pset. FLUKE INSANITY NOT PSET: The object pointed to by pset is not a port set object. FLUKE INSANITY INVALID OBJECT: The state of the object at pset is invalid, e.g. due to being overwritten by garbage. Related Information

,

,

,

,

fluke ipc setup wait receive fluke ipc send fluke ipc call fluke ipc reply fluke ipc client connect send fluke ipc side send fluke ipc side receive fluke ipc side disconnect

,

,

82

9 Mutexes

9.1 Overview

This section describes the Fluke API operations related to mutex objects.

9.2 State

The processor architecture-independent portion of a mutex object consists of:

uke mutex state

g;

struct integer t integer t

fluke ref t

;

f

/* attributes of the mutex ; /* TRUE if mutex is currently locked

flags locked

*/ */

*owner ref;

ags describes the attributes of the mutex object:

Speci es that the thread currently holding the mutex should inherit the CPU priority from any thread blocking on the mutex. MUTEX PRI CEILING Use the POSIX priority ceiling protocol. MUTEX MULTITASK Mutex is accessible to any thead that can access the object's memory. locked is non-zero if the mutex object is currently locked. owner ref is a reference to the thread object currently holding the mutex. If NULL, the mutex must be unlocked (locked is FALSE). MUTEX INHERIT PRI

9.3 References

A mutex object may reference:  threads: The owner ref reference. A mutex object may be referenced by:  threads: The thread object waiting for ref reference.

83

9.4 uke mutex create: create a new mutex Synopsis

fluke error t

uke mutex create(fluke mutex t *new mutex);

Description

Creates a new mutex object. The mutex is initially unlocked and has no special attributes. Parameters

new mutex : A pointer to the address in the current task's address space at which to create the

new mutex object.

Errors

If any of the following errors is detected, the appropriate error code is returned: FLUKE NO MEMORY: Insucient kernel resources were available. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new mutex. FLUKE INSANITY NOT ALIGNED: new mutex is not properly aligned for a mutex object. Related Information

,

fluke mutex destroy fluke mutex set state

84

9.5 uke mutex destroy: destroy a mutex

Synopsis void

uke mutex destroy(fluke mutex t *mutex);

Description

Destroys an active mutex created with fluke mutex create. Mutexes may only be destroyed while unlocked; attempting to destroy a locked mutex produces unde ned behavior. Parameters

mutex : The mutex to destroy. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mutex does not point to an active object. FLUKE INSANITY NOT MUTEX: The object pointed to by mutex is not a mutex object. FLUKE INSANITY INVALID OBJECT: The state of the mutex object has become invalid. FLUKE INSANITY MUTEX LOCKED: The mutex is still locked by some thread. Related Information fluke mutex create

85

9.6 uke mutex get state: retrieve the current state of a mutex

Synopsis

uke mutex get state(fluke mutex t *mutex, [out] fluke mutex state *state, [out]

void fluke ref t *owner

ref);

Description

This operation retrieves the application-visible state of a mutex. The mutex itself is unaected by the operation. Parameters

mutex : The mutex whose state is to be retrieved. state : If non-null, the structure to ll in with the mutex state. owner ref : If non-null, the address of a reference object to associate with the mutex's owning

thread object.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mutex does not point to an active object. FLUKE INSANITY NOT MUTEX: The object pointed to by mutex is not a mutex object. FLUKE INSANITY INVALID OBJECT: The state of the mutex object has become invalid. FLUKE INSANITY NOT REF: owner ref does not point to a valid reference object. Related Information fluke mutex set state

86

9.7 uke mutex lock: lock a mutex object

Synopsis void

uke mutex lock(fluke mutex t *mutex);

Description

Lock a mutex. Parameters

mutex : The mutex to lock. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mutex does not point to an active object. FLUKE INSANITY INVALID OBJECT: The state of the mutex object has become invalid.

87

9.8 uke mutex move: move a mutex object from one location to another Synopsis void

uke mutex move(fluke mutex t *old addr, fluke mutex t *new addr);

Description

Moves the speci ed active mutex object from one location in the caller's address space to another. The memory addressed by new addr must not already contain any active Fluke objects. On return, the mutex object will reside at new addr and the memory left behind at old addr will have unde ned contents. Parameters

old addr : The address of the mutex object to move. new addr : The location in memory to which the mutex is to be moved. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: old addr does not point to an active object. FLUKE INSANITY NOT MUTEX: The object pointed to by old addr is not a mutex object. FLUKE INSANITY INVALID OBJECT: The state of the mutex object has become invalid. FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new addr. FLUKE INSANITY NOT ALIGNED: new addr is not properly aligned for a mutex object.

88

9.9 uke mutex reference: associates a reference with a mutex Synopsis void

uke mutex reference(fluke mutex t *mutex, [out] fluke ref t *new mutex ref);

Description

This function associates an active reference object with the speci ed active mutex object. Parameters

mutex : The mutex object to which the new reference will refer. new mutex ref : A pointer to a valid reference object. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mutex or new mutex ref does not point to an active object. FLUKE INSANITY NOT MUTEX: The object pointed to by mutex is not a mutex object. FLUKE INSANITY INVALID OBJECT: The state of the mutex object has become invalid. FLUKE INSANITY NOT REF: new mutex ref does not point to a valid reference object.

89

9.10 uke mutex set state: set the current state of a mutex object

Synopsis

uke mutex set state(fluke mutex t *mutex, fluke mutex state *state, fluke ref t

void *owner

ref);

Description

This operation can be used to set the application-visible state of a mutex. Parameters

mutex : The mutex whose state is to be modi ed. state : If non-null, a pointer to a structure containing the state of the mutex. owner ref : If non-null, indicates the reference object to be inserted as the mutex's owner thread

reference.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mutex does not point to an active object. FLUKE INSANITY NOT MUTEX: The object pointed to by mutex is not a mutex object. FLUKE INSANITY INVALID OBJECT: The provided mutex state contains invalid information. FLUKE INSANITY NOT REF: The object at owner ref is not a reference object. FLUKE INSANITY NOT THREAD REF: The object at owner ref is a reference object, but not a reference to a thread. Related Information fluke mutex get state

90

9.11 uke mutex trylock: attempt to lock a mutex object Synopsis

fluke error t

uke mutex trylock(fluke mutex t *mutex);

Description

Attempt to acquire a mutex. If the mutex is held, the call returns immediately with a failure indication instead of blocking. Parameters

mutex : The mutex to lock. Returns

Returns FLUKE SUCCESS if the mutex was successfully locked or an error code if not. Errors

If any of the following errors is detected, the appropriate error code is returned: a reply is generated with the appropriate error code in the rst word of the reply: FLUKE MUTEX HELD: The mutex is currently locked. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mutex does not point to an active object. FLUKE INSANITY NOT MUTEX: The object pointed to by mutex is not a mutex object. FLUKE INSANITY INVALID OBJECT: The state of the mutex object has become invalid.

91

9.12 uke mutex unlock: lock a mutex object Synopsis void

uke mutex unlock(fluke mutex t *mutex);

Description

Release a mutex. Parameters

mutex : The mutex to unlock. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: mutex does not point to an active object. FLUKE INSANITY NOT MUTEX: The object pointed to by mutex is not a mutex object. FLUKE INSANITY INVALID OBJECT: The state of the mutex object has become invalid. FLUKE INSANITY MUTEX NOT LOCKED: The mutex is not currently locked. FLUKE INSANITY MUTEX NOT OWNER: The mutex is currently held, but not by the current thread.

92

10 Condition Variables

10.1 Overview

This section describes the Fluke API operations related to condition variable objects.

10.2 State

The processor architecture-independent portion of a condition variable object consists of:

uke cond state

g;

struct integer t

fluke ref t

f

; /* attributes of the condition variable

flags

*/

*inheritor ref;

ags describes the attributes of the condition variable object:

COND MULTITASK

The condition variable is accessible to any thead that can access the object's memory.

inheritor ref is a reference to the thread object which is targeted for priority inheritance. Null if no

thread is targeted.

10.3 References

A condition variable object may reference:  threads: The inheritor ref reference. A condition variable object may be referenced by:  threads: The thread object waiting for ref reference.

93

10.4 uke cond broadcast: broadcast on a condition variable object

Synopsis void

uke cond broadcast(fluke cond t *cond);

Description

Wakeup all threads waiting on a condition variable. Parameters

cond : The condition variable to broadcast on. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: cond does not point to an active object. FLUKE INSANITY INVALID OBJECT: The state of the condition variable object has become invalid.

94

10.5 uke cond create: create a new condition variable Synopsis

fluke error t

uke cond create(fluke cond t *new cond);

Description

Creates a new condition variable object. Parameters

new cond : A pointer to the address in the current task's address space at which to create the new

condition variable object.

Errors

If any of the following errors is detected, the appropriate error code is returned: FLUKE NO MEMORY: Insucient kernel resources were available. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new cond. FLUKE INSANITY NOT ALIGNED: new cond is not properly aligned for a condition variable object. Related Information fluke cond destroy

95

10.6 uke cond destroy: destroy a condition variable Synopsis void

uke cond destroy(fluke cond t *cond);

Description

Destroys an active condition variable created with fluke cond create. Condition variables may only be destroyed when no threads are waiting on them; attempting to destroy a condition variable that threads are waiting on produces unde ned results. Parameters

cond : The condition variable to destroy. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: cond does not point to an active object. FLUKE INSANITY NOT COND: The object pointed to by cond is not a condition variable object. FLUKE INSANITY INVALID OBJECT: The state of the condition variable object has become invalid. FLUKE INSANITY COND WAITING THREADS: One or more other threads are still waiting on the condition variable. Related Information fluke cond create

96

10.7 uke cond get state: retrieve the current state of a condition variable Synopsis

uke cond get state(fluke cond t *cond, [out] fluke cond state *state, [out] fluke ref t

void *inheritor

ref);

Description

This operation retrieves the application-visible state of a condition variable. The condition variable itself is unaected by the operation. Parameters

cond : The condition variable whose state is to be retrieved. state : If non-null, the structure to ll in with the condition variable state. inheritor ref : If non-null, the address of a reference object to associate with the mutex's inheritor

thread object.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: cond does not point to an active object. FLUKE INSANITY NOT COND: The object pointed to by cond is not a condition variable object. FLUKE INSANITY INVALID OBJECT: The state of the condition variable object has become invalid. FLUKE INSANITY NOT REF: inheritor ref does not point to a valid reference object. Related Information fluke cond set state

97

10.8 uke cond move: move a condition variable object from one location to another Synopsis void

uke cond move(fluke cond t *old addr, fluke cond t *new addr);

Description

Moves the speci ed active condition variable object from one location in the caller's address space to another. The memory addressed by new addr must not already contain any active Fluke objects. On return, the condition variable object will reside at new addr and the memory left behind at old addr will have unde ned contents. Parameters

old addr : The address of the condition variable object to move. new addr : The location in memory to which the condition variable is to be moved. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: old addr does not point to an active object. FLUKE INSANITY NOT COND: The object pointed to by old addr is not a condition variable object. FLUKE INSANITY INVALID OBJECT: The state of the condition variable object has become invalid. FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new addr. FLUKE INSANITY NOT ALIGNED: new addr is not properly aligned for a condition variable object.

98

10.9 uke cond reference: associates a reference with a condition variable

Synopsis void

uke cond reference(fluke cond t *cond, [out] fluke ref t *new cond ref);

Description

This function associates an active reference object with the speci ed active condition variable object. Parameters

cond : The condition variable object to which the new reference will refer. new cond ref : A pointer to a valid reference object. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: cond or new cond ref does not point to an active object. FLUKE INSANITY NOT COND: The object pointed to by cond is not a condition variable object. FLUKE INSANITY INVALID OBJECT: The state of the condition variable object has become invalid. FLUKE INSANITY NOT REF: new cond ref does not point to a valid reference object.

99

10.10 uke cond set state: set the current state of a condition variable object Synopsis void

uke cond set state(fluke cond t *cond, fluke cond state *state);

Description

This operation can be used to set the application-visible state of a condition variable. Parameters

cond : The condition variable whose state is to be modi ed. state : If non-null, a pointer to a structure containing the state of the condition variable. inheritor ref : The address of a thread reference object to be copied into the condition variables's

inheritor reference slot.

Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: cond does not point to an active object. FLUKE INSANITY NOT COND: The object pointed to by cond is not a condition variable object. FLUKE INSANITY INVALID OBJECT: The provided condition variable state contains invalid information. FLUKE INSANITY NOT REF: The object at inheritor ref is not a reference object. FLUKE INSANITY NOT THREAD REF: The object at inheritor ref is a reference object, but not a reference to a thread. Related Information fluke cond get state

100

10.11 uke cond signal: signal on a condition variable object

Synopsis void

uke cond signal(fluke cond t *cond);

Description

Wakeup one thread waiting on a condition variable. Parameters

cond : The condition variable to signal. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: cond does not point to an active object. FLUKE INSANITY NOT COND: The object pointed to by cond is not a condition variable object. FLUKE INSANITY INVALID OBJECT: The state of the condition variable object has become invalid.

101

10.12 uke cond wait: wait on a condition variable object

Synopsis void

uke cond wait(fluke cond t *cond, fluke mutex t *mutex);

Description

Wait for either a fluke cond broadcast or a fluke cond signal directed to this thread. Atomically releases the given mutex before blocking. Parameters

cond : The condition variable to wait on. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: cond does not point to an active object. FLUKE INSANITY NOT COND: The object pointed to by cond is not a condition variable object. FLUKE INSANITY INVALID OBJECT: The state of the condition variable object has become invalid. FLUKE INSANITY MUTEX NOT LOCKED: The speci ed mutex associated with this condition variable was not locked before the call to cond wait. FLUKE INSANITY MUTEX NOT OWNER: The associated mutex was locked, but not by the current thread. FLUKE INSANITY COND WRONG MUTEX: One or more threads are already waiting on the condition but speci ed a dierent associated mutex.

102

11 References 11.1 Overview

This section describes the Fluke API operations related to reference objects. Reference objects contain a \link" to another object. The association of a reference to its object is created either explicitly by fluke object reference calls or implicitly by the Fluke kernel when returning state with fluke object get state calls or when receiving references with fluke ipc side receive calls. There is no operation to return the object that a reference object is assiciated with (since the referenced object itself may not be mapped into the address space of the querying thread). However, given an unknown reference, an application can create an explicit reference to an object and compare that to the unknown reference to determine if they are equivalent. There is also an operation to determine if a reference is NULL. Reference objects are useful for determining equivalence with other references returned in object state (as decribed above). Some types of object references (port, mapping) are also used as capabilities. Not all types of objects are referencable.

11.2 State

Reference objects contain no saveable state.

11.3 References

Reference objects can reference all referencable objects; i.e. all object types except references and port sets. Reference objects cannot themselves be referenced in the conventional way; i.e. a reference object cannot be associated with another reference object.

103

11.4 uke ref check: determine if a reference is non-NULL Synopsis int

uke ref check(fluke ref t *ref);

Description

This function determines if the given reference object referring to a valid Fluke object or is NULL. Parameters

ref : The reference object to check. Returns

Returns 1 if the reference is non-NULL, 0 if it is NULL. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: ref does not point to an active object. FLUKE INSANITY NOT REF: The object pointed to by ref is not a reference object.

104

11.5 uke ref compare: determine if two references are equivalent Synopsis int

uke ref compare(fluke ref t *ref1, fluke ref t *ref2);

Description

This function determines if the given references are equivalent, returning true (nonzero) if they refer to the same Fluke object, or false if they do not. A NULL reference is never equivalent to any non-NULL reference; however, comparing two NULL references returns an unde ned result. Parameters

ref1 : One reference object to compare. ref2 : The other reference object to compare. Returns

Returns 1 if the references equivalent, 0 if not. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: ref1 or ref2 does not point to an active object. FLUKE INSANITY NOT REF: The object pointed to by ref1 or ref2 is not a reference object.

105

11.6 uke ref copy: make a copy of a reference object Synopsis void

uke ref copy(fluke ref t *src ref, fluke ref t *dst ref);

Description

Makes the reference object at dst ref reference the same thing as src ref. Any former association for the destination is severed. Parameters

src ref : The address of the reference object to copy. dst ref : The valid reference object which becomes the copy. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: src ref or dst ref does not point to an active object. FLUKE INSANITY NOT REF: The object pointed to by src ref or dst ref is not a reference object. FLUKE INSANITY INVALID OBJECT: The state of src ref or dst ref has become invalid.

106

11.7 uke ref create: create a new reference object Synopsis

fluke error t

uke ref create(fluke ref t *new ref);

Description

Creates a new reference object. The reference is initially not associated with any object; i.e. it is NULL. Parameters

new ref : A pointer to the address in the current task's address space at which to create the new

reference object.

Errors

If any of the following errors is detected, the appropriate error code is returned: FLUKE NO MEMORY: Insucient kernel resources were available. If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new ref. FLUKE INSANITY NOT ALIGNED: new ref is not properly aligned for a reference object. Related Information fluke ref destroy

107

11.8 uke ref destroy: destroy a reference Synopsis void

uke ref destroy(fluke ref t *ref);

Description

Destroys an active reference created with fluke ref create. Destruction of the reference does not aect the object referenced. Parameters

ref : The reference to destroy. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: ref does not point to an active object. FLUKE INSANITY NOT REF: The object pointed to by ref is not a reference object. Related Information fluke ref create

108

11.9 uke ref move: move a reference object from one location to another Synopsis void

uke ref move(fluke ref t *old addr, fluke ref t *new addr);

Description

Moves the speci ed active reference object from one location in the caller's address space to another. The memory addressed by new addr must not already contain any active Fluke objects. On return, the reference object will reside at new addr and the memory left behind at old addr will have unde ned contents. Parameters

old addr : The address of the reference object to move. new addr : The location in memory to which the reference is to be moved. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: old addr does not point to an active object. FLUKE INSANITY NOT REF: The object pointed to by old addr is not a reference object. FLUKE INSANITY INVALID OBJECT: The state of the reference object has become invalid. FLUKE INSANITY OBJECT EXISTS: An object already exists at the location pointed to by new addr. FLUKE INSANITY NOT ALIGNED: new addr is not properly aligned for a reference object.

109

11.10 uke ref type: return the type of an object associated with a reference Synopsis

fluke type t

uke ref type(fluke ref t *ref);

Description

This operation can be used to determine the type of the object associated with a reference. Returns the appropriate Fluke object type or FLUKE NULL if no object is associated with the reference object. Parameters

ref : The reference to look up. Errors

If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes: FLUKE INSANITY NO OBJECT: ref does not point to an active object. FLUKE INSANITY NOT REF: The object pointed to by ref is not a reference object. FLUKE INSANITY INVALID OBJECT: The provided reference state contains invalid information.

110