go

Algorithms for Image Processing and Computer Vision Source Code

@subheading Syntax

@example
#include <dpmi.h>

u_long _go32_dpmi_remaining_physical_memory();
@end example

@subheading Description

Returns the amount of physical memory that is still available in the
system. 

@subheading Return Value

The amount in bytes.

@c ----------------------------------------------------------------------
@node _go32_dpmi_remaining_virtual_memory, dpmi
@heading @code{_go32_dpmi_remaining_virtual_memory}
@subheading Syntax

@example
#include <dpmi.h>

u_long _go32_dpmi_remaining_virtual_memory();
@end example

@subheading Description

Returns the amount of virtual memory that is still available in the
system. 

@subheading Return Value

The amount in bytes.

@c ----------------------------------------------------------------------
@node _go32_dpmi_resize_dos_memory, dpmi
@heading @code{_go32_dpmi_resize_dos_memory}
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_resize_dos_memory(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{Go32/DPMI Information}

The @var{info} structure is the same one used to allocate the memory. 
Fill in a new value for @code{size} and call this function.  If there is
not enough memory to satisfy the request, the largest size is filled in
to the @code{size} field, the memory is not resized, and this function
fails. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
_go32_dpmi_seginfo info;
info.size = 10;
_go32_dpmi_allocate_dos_memory(&info);
info.size = 20;
_go32_dpmi_resize_dos_memory(&info);
_go32_dpmi_free_dos_memory(&info);
@end example

@c ----------------------------------------------------------------------
@node _go32_dpmi_set_protected_mode_interrupt_vector, dpmi
@heading @code{_go32_dpmi_set_protected_mode_interrupt_vector}
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_set_protected_mode_interrupt_vector(int vector, _go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function sets the protected mode interrupt vector specified to
point to the given function.  The @code{pm_offset} and
@code{pm_selector} fields of @var{info} must be filled in
(@pxref{_go32_my_cs}).  The following should be noted:

@itemize @bullet

@item

You may not @code{longjmp} out of an interrupt handler.

@item

You may not make any function calls that require go32's assistance, such
as @code{printf}. 

@item

This function will not wrap the handler for you.  The
@code{_go32_dpmi_allocate_iret_wrapper} and
@code{_go32_dpmi_chain_protected_mode_interrupt_vector} functions can
wrap your function if you want.

@item

You must set the pm_selector field of @var{info}.  Use
@code{_go32_my_cs} to get a selector valid for your functions. 

@end itemize

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
volatile int tics = 0;

timer_handler()
@{
  tics++;
@}

int main()
@{
  _go32_dpmi_seginfo old_handler, new_handler;

  printf("grabbing timer interrupt\n");
  _go32_dpmi_get_protected_mode_interrupt_vector(8, &old_handler);
  
  new_handler.pm_offset = (int)tic_handler;
  new_handler.pm_selector = _go32_my_cs();
  _go32_dpmi_chain_protected_mode_interrupt_vector(8, &new_handler);

  getkey();

  printf("releasing timer interrupt\n");
  _go32_dpmi_set_protected_mode_interrupt_vector(8, &old_handler);

  return 0;
@}

@end example

@c ----------------------------------------------------------------------
@node _go32_dpmi_set_real_mode_interrupt_vector, dpmi
@heading @code{_go32_dpmi_set_real_mode_interrupt_vector}
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_set_real_mode_interrupt_vector(int vector, _go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function sets the real-mode interrupt vector specified to point to
the address in the @code{rm_segment} and @code{rm_offset} fields in
@var{info}.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}

@c ----------------------------------------------------------------------
@node _go32_dpmi_simulate_fcall, dpmi
@heading @code{_go32_dpmi_simulate_fcall}
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_simulate_fcall(_go32_dpmi_registers *regs);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function simulates a real-mode far call to a function that returns
with a far return.  The registers are set up from @var{regs}, including
@code{CS} and @code{IP}, which indicate the address of the call.  Any
registers the function modifies are reflected in @var{regs} on return.

If @code{SS} and @code{SP} are both zero, a small temporary stack is
used when in real mode.  If not, they are used AS IS.  It's a good
idea to use @code{memset} to initialize the register structure before
using it.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
_go32_dpmi_registers r;
r.x.ax = 47;
r.x.cs = some_segment;
r.x.ip = some_offset;
r.x.ss = r.x.sp = 0;
_go32_dpmi_simulate_fcall(&r);
printf("returns %d\n", r.x.ax);
@end example

@c ----------------------------------------------------------------------
@node _go32_dpmi_simulate_fcall_iret, dpmi
@heading @code{_go32_dpmi_simulate_fcall_iret}
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_simulate_fcall_iret(_go32_dpmi_registers *regs);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function simulates a real-mode far call to a function that returns
with an @code{iret} instruction.  The registers are set up from
@var{regs}, including @code{CS} and @code{IP}, which indicate the
address of the call.  Any registers the function modifies are reflected
in @var{regs} on return. 

If @code{SS} and @code{SP} are both zero, a small temporary stack is
used when in real mode.  If not, they are used AS IS.  It's a good
idea to use @code{memset} to initialize the register structure before
using it.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
_go32_dpmi_registers r;
r.x.ax = 47;
r.x.cs = some_segment;
r.x.ip = some_offset;
r.x.ss = r.x.sp = 0;
_go32_dpmi_simulate_fcall_iret(&r);
printf("returns %d\n", r.x.ax);
@end example

@c ----------------------------------------------------------------------
@node _go32_dpmi_simulate_int, dpmi
@heading @code{_go32_dpmi_simulate_int}
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_simulate_int(int vector, _go32_dpmi_registers *regs);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function simulates a real-mode interrup.  The registers are set up from
@var{regs}, including @code{CS} and @code{IP}, which indicate the
address of the call.  Any registers the function modifies are reflected
in @var{regs} on return. 

If @code{SS} and @code{SP} are both zero, a small temporary stack is
used when in real mode.  If not, they are used AS IS.  It's a good
idea to use @code{memset} to initialize the register structure before
using it.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
_go32_dpmi_registers r;
r.h.ah = 0x08;
r.h.dl = 0x80; /* drive C: */
r.x.ss = r.x.sp = 0;
_go32_dpmi_simulate_int(0x13, &r);
printf("disk is %d cyl, %d head, %d sect\n",
       r.h.ch | ((r.x.cl<<2)&0x300),
       r.h.dh, r.h.cl & 0x3f));
@end example

@c ----------------------------------------------------------------------
@node _go32_info_block, dpmi
@heading @code{_go32_info_block}
@subheading Syntax

@example
#include <go32.h>

extern Go32_Info_Block _go32_info_block;
@end example

@subheading Description

The go32 information block is a mechanism for @file{go32} to pass
information to the application.  Some of this information is generally
useful, such as the pid or the transfer buffer, while some is used
internally to @file{libc.a} only. 

The structure has this format:

@example
typedef struct @{
  u_long size_of_this_structure_in_bytes;
  u_long linear_address_of_primary_screen;
  u_long linear_address_of_secondary_screen;
  u_long linear_address_of_transfer_buffer;
  u_long size_of_transfer_buffer;
  u_long pid;
  u_char master_interrupt_controller_base;
  u_char slave_interrupt_controller_base;
  u_short selector_for_linear_memory;
  u_long linear_address_of_stub_info_structure;
  u_long linear_address_of_original_psp;
  u_short run_mode;
  u_short run_mode_info;
@} Go32_Info_Block;
@end example

The linear address fields provide values that are suitable for
@code{dosmemget} and @code{dosmemput}.  If you want to use them with
movedata, you must mask off the top four bits, which are set to
special values that go32 uses to detect when you've already
transferred the data to the transfer buffer.

The @code{run_mode} field indicates the mode that the program is running
in.  The following modes are defined:

@table @code

@item _GO32_RUN_MODE_UNDEF

This indicates that the extender did not (or could not) determine or
provide the mode information.  The most probable reason is that it's an
older extender that does not support this field.  The program should not
assume anything about the run mode if it is this value. 

@item _GO32_RUN_MODE_RAW

This indicates that no CPU manager is being used, and no XMS manager is
present.  The CPU is being managed directly from the extender, and
memory was allocated from the extended memory pool. 

@item _GO32_RUN_MODE_XMS

This indicates that the extender is managing the CPU, but an XMS driver
is managing the memory pool. 

@item _GO32_RUN_MODE_VCPI

This indicates that a VCPI server (like @code{emm386} or @code{qemm}) is
managing both the CPU and the memory. 

@item _GO32_RUN_MODE_DPMI

This indicates that a DPMI server (like @code{qdpmi} or Windows) is
managing both the CPU and memory.  Programs may rely on this value
to determine if it is safe to use DPMI 0.9 functions.

If this value is set, the @code{run_mode_info} field has the DPMI
specification version, in hex, shifted eight bits.  For example, DPMI
0.9 has 0x0090 in the @code{run_mode_info} field. 

@end table

Note that the program should not assume that the value will be one of
the listed values.  If the program is running with an extender that
provides some other mode (say, a newly released extender) then the
program should be able to handle that case gracefully. 

@subheading Example

@example
dosmemget(_go32_info_block.linear_address_of_primary_screen, 80*25*2, buf);
@end example

@c ----------------------------------------------------------------------
@node _go32_my_cs, go32
@heading @code{_go32_my_cs}
@subheading Syntax

@example
#include <go32.h>

u_short _go32_my_cs();
@end example

@subheading Description

Returns the current @code{CS}.  This is useful for setting up interrupt
vectors and such. 

@subheading Return Value

@code{CS}

@c ----------------------------------------------------------------------
@node _go32_my_ds, go32
@heading @code{_go32_my_ds}
@subheading Syntax

@example
#include <go32.h>

u_short _go32_my_ds();
@end example

@subheading Description

Returns the current @code{DS}.  This is useful for setting up interrupt
handlers and such. 

@subheading Return Value

@code{DS}

@c ----------------------------------------------------------------------
@node _go32_my_ss, go32
@heading @code{_go32_my_ss}
@subheading Syntax

@example
#include <go32.h>

u_short _go32_my_ss();
@end example

@subheading Description

Returns the current @code{SS}.  This is useful for setting up interrupt
handlers and such. 

@subheading Return Value

@code{SS}

@c ----------------------------------------------------------------------
@node _go32_want_ctrl_break, go32
@heading @code{_go32_want_ctrl_break}
@subheading Syntax

@example
#include <go32.h>

void   _go32_want_ctrl_break(int yes);
@end example

@subheading Description

This function tells go32 whether or not it wants @kbd{Ctrl-Break} to be
an exception or passed to the application.  If you pass a nonzero value
for @var{yes}, pressing @kbd{Ctrl-Break} will set a flag that can be
detected with @code{_go32_was_ctrl_break_hit}
(@pxref{_go32_was_ctrl_break_hit}).  If you pass zero for @var{yes}, When
you press @kbd{Ctrl-Break} the program will be terminated. 

Note that if you call @code{_go32_was_ctrl_break_hit}, this function
automatically gets called to ask for @kbd{Ctrl-Break} events. 

@subheading Return Value

None.

@subheading Example

@example
_g32_want_ctrl_break(1);
do_something_long();
_g32_want_ctrl_break(0);
@end example

@c ----------------------------------------------------------------------
@node _go32_was_ctrl_break_hit, go32
@heading @code{_go32_was_ctrl_break_hit}
@subheading Syntax

@example
#include <go32.h>

u_long _go32_was_ctrl_break_hit();
@end example

@subheading Description

This function returns the number of times that @kbd{Ctrl-Break} was hit
since the last call to this function or @code{_go32_want_ctrl_break}
(@pxref{_go32_want_ctrl_break}). 

@subheading Return Value

Zero if @kbd{Ctrl-Break} hasn't been hit, nonzero to indicate how many
times if it has been hit. 

Note that @code{_go32_want_ctrl_break} is automatically called to
request these events, so you don't have to set up for this call. 

@subheading Example

@example
while (!_go32_was_ctrl_break_hit())
  do_something();
@end example