8.19 Process library

This library is only available on GEM XM. These functions allow to run up to 10 GEM and DOS applications at once, swapping out to eXpanded Memory (XM) or to disk. Each process uses a 'channel' to store its system area, work area, interrupt table and swap file.

• proc_create	Create a new process
• proc_delete	Close all desk accessories
• proc_info	Obtain info about a process
• proc_malloc	Allocate memory
• proc_mfree	Release memory
• proc_run	Run process
• proc_setblock	Shrink channel and create swap file
• proc_shrink	Shrink channel with optional swap creation
• proc_switch	Switch to process

8.19.1 proc_create

Name:

»Process create« - Create a new process

Opcode:

Syntax:

int16_t proc_create ( void *address, int32_t size, int16_t is_swap, int16_t is_gem, int16_t *num );

Description:

The call proc_create allocates a new process ID but does not launch the process. The following apply:

address	Channel address at which to load process
size	Space to allocate, or 0 to allocate maximum channel space
is_swap	Nonzero if the process can be swapped out, zero if it must stay paged in. The GEM XM Desktop marks accessories as not to be paged out
is_gem	Nonzero if the process is a GEM application, zero for DOS application
num	Process ID of new process

Note: Since GEM XM doesn't support having more than one newly-launched process waiting around, the process with ID num must be launched through proc_run before calling proc_create again.

Return value:

An error has arisen only if the value 0 is returned (no more ID available).

Availability:

This function is only available under GEM XM and FreeGEM/XM.

Group:

Process library

8.19.1.1 Bindings for proc_create

int16_t proc_create ( void *address, int32_t size, int16_t is_swap, int16_t is_gem, int16_t *num );

Binding:

int16_t proc_create (void *address, int32_t size, int16_t is_swap,
                 int16_t is_gem, int16_t *num)
{
   int_in[0]  = is_swap;
   int_in[1]  = is_gem;
   addr_in[0] = address;
   addr_in[1] = size;

   crys_if(60);

   *num = int_out[1];

   return ( int_out[0] );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	60 # Function opcode
control+2	control[1]	2 # Entry in int_in
control+4	control[2]	2 # Entry in int_out
control+6	control[3]	2 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_in	int_in[0]	is_swap
int_in+2	int_in[1]	is_gem
addr_in	addr_in[0]	address
addr_in+4	addr_in[1]	size
int_out	int_out[0]	Return value
int_out+2	int_out[1]	num

8.19.2 proc_delete

Name:	»Process delete« - Close all desk accessories
Opcode:	62
Syntax:	int16_t proc_delete ( int16_t pr_deid );
Description:	The call proc_delete shuts down all desk accessories. The pr_deid parameter is ignored, but Desktop uses -1.
Return value:	Return value of the function is unknown at present.
Availability:	The function is only available under GEM XM and FreeGEM/XM.
Group:	Process library
See also:	Binding

8.19.2.1 Bindings for proc_delete

int16_t proc_delete ( int16_t pr_deid );

Binding:

int16_t proc_delete (int16_t pr_deid)
{
   int_in[0]  = pr_deid;
   return ( crys_if(62) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	62 # Function opcode
control+2	control[1]	1 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	0 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_in	int_in[0]	pr_deid
int_out	int_out[0]	Return value

8.19.3 proc_info

Name:

»Process information« - Obtains information about a process

Opcode:

Syntax:

int16_t proc_info ( int16_t pid, int16_t *is_swap, int16_t *is_gem, void **address, int32_t *csize, void **endmem, int32_t *ssize, void **intaddr );

Description:

The call proc_info inquires information about a process. The following apply:

pid	Process ID about which to get info
is_swap	Nonzero if swappable, else zero
is_gem	Nonzero for a GEM application, zero for a DOS application
address	Address of channel
csize	Size of channel
endmem	First address beyond end of process memory
ssize	Channel system size
intaddr	Address of process's copy of the interrupt vector table

Return value:

An error has arisen only if the value 0 is returned.

Availability:

The function is only available under GEM XM and FreeGEM/XM.

Group:

Process library

8.19.3.1 Bindings for proc_info

int16_t proc_info ( int16_t pid, int16_t *is_swap, int16_t *is_gem, void **address, int32_t *csize, void **endmem, int32_t *ssize, void **intaddr );

Binding:

int16_t proc_info (int16_t pid, int16_t *is_swap, int16_t *is_gem,
              void **address, int32_t *csize, void **endmem,
              int32_t *ssize, void **intaddr)
{
   int_in[0]  = pid;

   crys_if(63);

   *is_swap  = int_out[1];
   *is_gem   = int_out[2];
   *address  = addr_out[0];
   *csize    = addr_out[1];
   *endmem   = addr_out[2];
   *ssize    = addr_out[3];
   *intaddr  = addr_out[4];

   return ( int_out[0] );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	63 # Function opcode
control+2	control[1]	1 # Entry in int_in
control+4	control[2]	3 # Entry in int_out
control+6	control[3]	0 # Entry in addr_in
control+8	control[4]	5 # Entry in addr_out
int_in	int_in[0]	pid
int_out	int_out[0]	Return value
int_out+2	int_out[1]	is_swap
int_out+4	int_out[2]	is_gem
addr_out	addr_out[0]	address
addr_out+4	addr_out[1]	csize
addr_out+8	addr_out[2]	endmem
addr_out+12	addr_out[3]	ssize
addr_out+16	addr_out[4]	intaddr

8.19.4 proc_malloc

Name:	»Process memory allocation« - Allocate memory
Opcode:	64
Syntax:	void proc_malloc ( int32_t size, int32_t ret_size );
Description:	The call proc_malloc allocates a memory block of size bytes.
Return value:	The function returns a pointer to the allocated memory block, or 0 if failed. ret_size is filled with either the size of the allocated memory block, or with the maximum available size.
Availability:	The function is only available under GEM XM and FreeGEM/XM.
Group:	Process library
See also:	Binding proc_mfree proc_setblock proc_shrink

8.19.4.1 Bindings for proc_malloc

void *proc_malloc ( int32_t size, int32_t *ret_size );

Binding:

void *proc_malloc (int32_t size, int32_t *ret_size)
{
   addr_in[0] = size;

   crys_if(64);

   *ret_size = addr_out[1];

   return ( addr_out[0] );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	64 # Function opcode
control+2	control[1]	0 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	1 # Entry in addr_in
control+8	control[4]	2 # Entry in addr_out
addr_in	addr_in[0]	size
int_out	int_out[0]	1 if success, or 0 if failure
addr_out	addr_out[0]	Return value
addr_out+4	addr_out[1]	ret_size

8.19.5 proc_mfree

Name:	»Process memory free« - Release memory
Opcode:	65
Syntax:	int16_t proc_mfree ( int16_t pr_mfid );
Description:	The call proc_mfree deletes the channel associated to the process ID pr_mfid from memory and disk for reuse.
Return value:	An error has arisen if the value 0 is returned.
Availability:	This function is only available under GEM XM and FreeGEM/XM.
Group:	Process library
See also:	Binding proc_malloc proc_setblock proc_shrink

8.19.5.1 Bindings for proc_mfree

int16_t proc_mfree ( int16_t pr_mfid );

Binding:

int16_t proc_mfree (int16_t pr_mfid)
{
   int_in[0]  = pr_mfid;
   return ( crys_if(65) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	65 # Function opcode
control+2	control[1]	1 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	0 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_in	int_in[0]	pr_mfid
int_out	int_out[0]	Return value

8.19.6 proc_run

Name:

»Process run« - Run a process

Opcode:

Syntax:

int16_t proc_run ( int16_t pid, int16_t is_graphical, int16_t options, int8_t *command, int8_t *tail );

Description:

The call proc_run launches a process previously created with proc_create. The following apply:

pid

Process ID previously returned by proc_create

is_graphical

Nonzero for a GEM program, zero for a DOS program

options

Special load options:

3	Program is a desk accessory
4	If this is a GEM program, its windows remain visible whichever program is in the foreground; otherwise they are only visible when the program in question is in the foreground
-1	If the gl_allwins flag is turned on, then behaves like type 4. Otherwise behaves as default. GEM provides no option to turn this flag on programmatically; you have to patch the AES by writing a nonzero value in the byte that follows the marker 'zyxg' inside the binary AES file.

command

Name of program to run

tail

Command tail to pass to it

Note: The odd range of values passed to the load options is chosen for compatibility with the isover flag of shel_write.

Return value:

An error has arisen only if the value 0 is returned.

Availability:

The function is only available under GEM XM and FreeGEM/XM.

Group:

Process library

8.19.6.1 Bindings for proc_run

int16_t proc_run ( int16_t pid, int16_t is_graphical, int16_t options, int8_t *command, int8_t *tail );

Binding:

int16_t proc_run (int16_t pid, int16_t is_graphical, int16_t options,
                 int8_t *command, int8_t *tail)
{
   int_in[0]  = pid;
   int_in[1]  = is_graphical;
   int_in[2]  = options;
   addr_in[0] = command;
   addr_in[1] = tail;

   return ( crys_if(61) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	61 # Function opcode
control+2	control[1]	3 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	2 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_in	int_in[0]	pid
int_in+2	int_in[1]	is_graphical
int_in+4	int_in[2]	options
addr_in	addr_in[0]	command
addr_in+4	addr_in[1]	tail
int_out	int_out[0]	Return value

8.19.7 proc_setblock

Name:	»Process set block« - Shrink channel and create swap file
Opcode:	67
Syntax:	int16_t proc_setblock ( int16_t pr_seid );
Description:	The call proc_setblock reduces the channel size allocated to the process pr_seid to what it is using now by eliminating its free memory, and creates the swap file used to page it out. Note This function calls proc_shrink(pr_seid, 1, &dummy, &dummy). The FreeGEM/XM Desktop defines this function as proc_shrink() with PROC_SHRINK=67 and omit to define a function for opcode 68. Original sources stated PROC_SETBLOCK=67 (with PID only) and PROC_SHRINK=68 (with extra parameters), as documented here.
Return value:	An error has arisen only if the value 0 is returned.
Availability:	The function is only available under GEM XM and FreeGEM/XM.
Group:	Process library
See also:	Binding proc_malloc proc_mfree proc_shrink

8.19.7.1 Bindings for proc_setblock

int16_t proc_setblock ( int16_t pr_seid );

Binding:

int16_t proc_setblock (int16_t pr_seid)
{
   int_in[0]  = pr_seid;
   return ( crys_if(67) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	67 # Function opcode
control+2	control[1]	1 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	0 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_in	int_in[0]	pr_seid
int_out	int_out[0]	Return value

8.19.8 proc_shrink

Name:	»Process shrink« - Shrink channel
Opcode:	68
Syntax:	int16_t proc_shrink ( int16_t pr_shid, int16_t createswap, void address, int32_t size );
Description:	The call proc_shrink reduces the size of the channel allocated to the process pr_shid to what it is using now by eliminating its free memory, and optionally creates the swap file used to page it out if createswap is set to 1. Note: This function is not used by FreeGEM/XM Desktop. On this environment, the function with opcode 67 is called proc_shrink and there is no binding for opcode 68.
Return value:	An error has arisen only if the value 0 is returned. On success, this function returns the new size and address of the channel.
Availability:	The function is only available under GEM XM.
Group:	Process library
See also:	Binding proc_malloc proc_mfree proc_setblock

8.19.8.1 Bindings for proc_shrink

int16_t proc_shrink ( int16_t pr_shid, int16_t createswap, void *address, int32_t *size );

Binding:

int16_t proc_shrink (int16_t pr_shid, int16_t createswap, void *address, int32_t *size)
{
   int_in[0]  = pr_shid;
   int_in[1]  = createswap;

   crys_if(68);

   *address = addr_out[0];
   *size    = addr_out[1];

   return ( int_out[0] );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	68 # Function opcode
control+2	control[1]	2 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	0 # Entry in addr_in
control+8	control[4]	2 # Entry in addr_out
int_in	int_in[0]	pr_shid
int_in+2	int_in[1]	createswap
int_out	int_out[0]	Return value
addr_out	addr_out[0]	address
addr_out+4	addr_out[1]	size

8.19.9 proc_switch

Name:	»Process switch« - Switch to process
Opcode:	66
Syntax:	int16_t proc_switch ( int16_t pr_swid );
Description:	The call proc_switch switches to process with the ID pr_swid.
Return value:	Returns 0 if process is already the active process, else 1.
Availability:	This function is only available under GEM XM and FreeGEM/XM.
Group:	Process library
See also:	Binding proc_create proc_info proc_run

8.19.9.1 Bindings for proc_switch

int16_t proc_switch ( int16_t pr_swid );

Binding:

int16_t proc_switch (int16_t pr_swid)
{
   int_in[0]  = pr_swid;
   return ( crys_if(66) );
}

GEM-Arrays:

Address	Element	Contents
control	control[0]	66 # Function opcode
control+2	control[1]	1 # Entry in int_in
control+4	control[2]	1 # Entry in int_out
control+6	control[3]	0 # Entry in addr_in
control+8	control[4]	0 # Entry in addr_out
int_in	int_in[0]	pr_swid
int_out	int_out[0]	Return value

AES

Object library

Property library