5 SV protocol

The task supervisor is responsible for the management of the task system. He creates tasks and threads and holds all informations about the task system. If you want to know something about the tasksystem or want to create a task or a thread, you have to communicate with the supervisor. The next sections describes the supervisor protocol and the C library. Caution! the current supervisor communicates with the old fashioned V2 ipc. You have to use the special V2 emulation (V2 emu dope and emu token).

5.2 Supervisorprotocol

begin

Purpose:

A new process is created.

Parameters:

• TEXT task name
• INT attributes
• instruction pointer
• stack pointer
• stdds {optional parameter}

attribut bits:

1..7 privilege

This field specifies the requested privilege of the new process (0=user, 1=privileged, 2=supervisor, 3=kernel). The effective privilege is the minimum of the requested privilege and the privilege of the requesting process.

8..15 associated intr

This field is relevant for hardware driver processes. It contains the number of the hardware interrupt (33..255), which should be linked to the new process. A value of 0 specifies 'no interrupt to be associated'.

16 resident

• = 0 The new process should be pageable and persistent. The creator must also be pageable.
• = 1 The new process should be resident. All pages allocated in the dataspace are loaded into main memory. They will never be swapped out. Resident processes are not persistent.

17..18 io permit

• = 00 The new process will have no access to IO ports. (IOPL=0 and io permission bitmap empty.)
• = 01 The new process may access selected IO ports (IOPL=0, non empty io permission bitmap). This mode is not yet implemented!
• = 11 The new process may access all IO ports and may disable interrupts (IOPL=3).

24 thread

• = 0 The new process should be autonomous, i.e a task with own address space and dataspaces.
• = 1 The new process should be a thread of the same task.

25 undeletable

• = 0 The new process may be deleted by its parent or a privileged task.
• = 1 The new process should be undeletable by others. It may delete itself or may be deleted by shutdown (if resident).

Instruction pointer and Stack pointer

Instruction pointer and stack pointer specify the initial values for the EIP and ESP registers of the new process. CS is loaded with 'espace' (base=0, size=16MB, use32, executable, readable). All other segment registers are loaded with 'dspace' (base=0,size=32MB, use32, readable, writable).

Dataspace

The optional dataspace message chapter is needed iff the thread bit in the attribute dword is reset, i.e. a stdds is needed only when creating a new task.

rename

Purpose:

The calling task or thread is renamed. (Caution! It gets an new version number)

Parameters:

TEXT new task name

end

Purpose:

The process 'task' is deleted. The end message is only allowed if:

     task = order task 
COR  (task < order task CAND task is deletable) 
COR  (order task < supervisor) CAND NOT (order task < task) 
CAND task is deletable) 

Parameters:

TASK task

halt

Purpose:

The process 'task' is halted, i.e. an error 'halt from terminal' is induced. The end message is only allowed if

     task = order task 
COR  task < order task 
COR  (order task < supervisor) CAND NOT (order task < task)) 

Parameters:

TASK task

halt

Parameters:

TASK task

Remark

Not yet implemented.

system catalogue

Purpose:

The system catalogue space is delivered.

Parameters:

TASK task

Result:

DATASPACE system catalogue space

father

Purpose:

The father task of task is delivered.

Parameters:

TASK task

Result:

TASK father of task

son

Purpose:

The first child task of task is delivered.

Parameters:

TASK task

Result:

TASK son of task. If there isn't any child task, it return nil task.

brother

Purpose:

The first brother task of task is delivered.

Parameters:

TASK task

Result:

TASK brother of task. If there isn't a brother task, it return nil task. It is possible to get nil task, although there are other tasks with the same parent. If you want to get all brothers of task x, get the father of task x, the son of this task and call brother(actual brother) starting with this child task until you get nil task.

name

Purpose:

The name of task task is delivered.

Parameters:

TASK task

Result:

TEXT name of task

task

Purpose:

The task id of task name of task is delivered.

Parameters:

TEXT name of task

Result:

TASK task. If there isn't a task with name name of task, nil task is delivered

exists task

Purpose:

Check for the existence of task name of task and return the result.

Parameters:

TEXT task name

Result:

BOOL flag. Caution: The supervisor return 0 for true and 1 for false.

set station name

Purpose:

The name of the station is set to new name of station.

Parameters:

TEXT new name of station

Precondition:

privilege (order task) >= system privilege

get station name

Purpose:

The name of the station is delivered.

Parameters:

None

Result:

TEXT name of station

supervisor version

Purpose:

The version number of the supervisor is delivered.

Parameters:

NONE

Result:

INT actual supervisor version

change supervisor

Parameters:

• TEXT dummy
• INT password
• INT dummy
• INT dummy
• DATASPACE new stdds

This chapter describes the library functions which provide an interface to the supervisor protocol. The function automatically transform the given identifiers into the format required by the supervisor and transform the results back to the format expected by the callee. The default identifier format is the version three format. If you want to use the version two format you have to include a #define V2_IPC before including svprot.h.

5.3.1 Parameters of SV C-Library

thread

The parameter thread is the id of a thread in the default format, for which an operation is requested. If a thread id is delivered, it is an id in the same format.

name

The parameter name is a normal zero terminated string representing the name of a thread or a station name.

max length

The parameter max length describes the maximum length of a delivered string. The buffer for the deliverd string should be at least as big as max length + 1.

return value

If the call was successful, the functions return the value L3_SV_ACK, otherwise L3_SV_NACK. If you try to rename yourself you can get a return value of L3_SV_ERR_NACK. That means, that you have to wait a certain time before you can request that operation again(1).

other parameters

[here]

void SVProtInit(void);

This function initializes the supervisorprotocol. It has to be the first call of this library.

int SVFather(ThreadT thread,ThreadT *father);

This function delivers the father of thread thread.

int SVBrother(ThreadT thread,ThreadT *brother);

This function delivers the first brother of thread thread. If there isn't a brother thread, it returns nil thread. It is possible to get nil thread, although there are other threads with the same parent. If you want to get all brothers of thread x, get the father of thread x, the son of this thread and call brother(actual brother) starting with this child thread until you get nil thread.

int SVSon(ThreadT thread,ThreadT *son);

This function delivers the first child thread of thread thread. If there isn't any child, it delivers nil thread.

int SVEnd(ThreadT thread);

     thread = order thread 
COR  (thread < order thread CAND thread is deletable) 
COR  (order thread < supervisor) CAND NOT (order thread < thread) 
CAND thread is deletable) 

int SVName(ThreadT thread, char *name, int maxlen);

This function delivers the zero terminated name of thread thread. The buffer name has to be at least as big as max length + 1.

int SVThread(char *name, ThreadT *thread);

This funtions delivers the thread id of the thread thread. If the thread doesn't exist, it returns nil thread.

int SVRename(char *newname);

This function renames the calling thread. The calling thread get's the new name newname and a new version number. This call isn't posible at all times. If a thread renames itself, it has to wait for a distinct time before it can rename itself again. The call returns i don't no , if this happens.

int SVHalt(ThreadT thread);

The process 'thread' is halted, i.e. an error 'halt from terminal' is induced. The end message is only allowed if

     thread = order thread
COR  thread < order thread
COR  (order thread < supervisor) CAND NOT (order thread < thread))

int SVCatalog(ThreadT thread, TDataSpace *ds);

todo

int SVExistsThread(char *name);

todo

int SVGetStationName(char *name, int maxlength);

todo

int SVSetStationName(char *name);

todo

int SVLessThen(char *name, char *precursor);

todo (unklar)

int SVBeginThread(char *name, int attrib, int ip, int sp, ThreadT *newthread);

This function creates a new thread with the name name [here]. The id of the new thread is returned in *newthread.

int SVBeginTask(char *name, int attrib, int ip, int sp, DATASPACE ds, ThreadT *firstthread);

This function creates a new task with the name name [here]. The id of the first thread of the new task is returned in *firstthread.