go

Algorithms for Image Processing and Computer Vision Source Code

@c ----------------------------------------------------------------------
@node go32.h, header
@heading @code{<go32.h>}

This header provides structure definitions and functions that access
functionality that is only available because of go32.

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

@example
#include <go32.h>

u_short _go32_conventional_mem_selector();
@end example

@subheading Description

This function returns a selector which has a physical base address
corresponding to the beginning of conventional memory.  This selector
can be used as a parameter to @code{movedata} (@pxref{movedata}) to
manipulate memory in the conventional address space. 

@subheading Return Value

The selector.

@subheading Example

@example
short blank_row_buf[ScreenCols()];
/* scroll screen */
movedata(_go32_conventional_mem_selector(), 0xb8000 + ScreenCols()*2,
         _go32_conventional_mem_selector(), 0xb8000,
         ScreenCols() * (ScreenRows()-1) * 2);
/* fill last row */
movedata(_go32_my_ds, (int)blank_row_buf,
         _go32_conventional_mem_selector(),
            0xb8000 + ScreenCols()*(ScreenRows()-1)*2,
          ScreenCols() * 2);
@end example

@c ----------------------------------------------------------------------
@node Go32/DPMI Information, dpmi
@heading GO32/DPMI structures
@subheading Syntax

@example
#include <dpmi.h>
@end example

@subheading Description

DPMI is an interface to the program controlling the protected mode of
the PC.  For more information on DPMI, order Intel document number
240977-001.  If there is no DPMI server running on the PC, go32 itself
will provide a subset of the DPMI functions.  For maximum portability,
programs should confine themselves to the specifications listed in the
file @file{docs/djgpp/dpmi.doc} in the DJGPP distribution.  The
convenience functions listed in @file{include/dpmi.h} comply with these
restrictions and thus will always be usable on a given PC. 

The DPMI convenience functions provided by go32 use two structures to
pass information around in.  These structures are shown below.

@example
typedef union @{
  struct @{
    u_long edi;
    u_long esi;
    u_long ebp;
    u_long res;
    u_long ebx;
    u_long edx;
    u_long ecx;
    u_long eax;
  @} d;
  struct @{
    u_short di, di_hi;
    u_short si, si_hi;
    u_short bp, bp_hi;
    u_short res, res_hi;
    u_short bx, bx_hi;
    u_short dx, dx_hi;
    u_short cx, cx_hi;
    u_short ax, ax_hi;
    u_short flags;
    u_short es;
    u_short ds;
    u_short fs;
    u_short gs;
    u_short ip;
    u_short cs;
    u_short sp;
    u_short ss;
  @} x;
  struct @{
    u_char edi[4];
    u_char esi[4];
    u_char ebp[4];
    u_char res[4];
    u_char bl, bh, ebx_b2, ebx_b3;
    u_char dl, dh, edx_b2, edx_b3;
    u_char cl, ch, ecx_b2, ecx_b3;
    u_char al, ah, eax_b2, eax_b3;
  @} h;
@} _go32_dpmi_registers;
@end example

The @code{_go32_dpmi_registers} structure is used to pass a CPU state
image between protected and real mode. 

@example
typedef struct @{
  u_long  size;
  u_long  pm_offset;
  u_short pm_selector;
  u_short rm_offset;
  u_short rm_segment;
@} _go32_dpmi_seginfo;
@end example

The @code{_go32_dpmi_seginfo} structure is used to pass information
about protected mode and real mode pointers to the convenience
functions.  Unless stated otherwise, you should not modify any field in
this structure.  Many calls store important information in otherwise
unused fields that is used in cleanup-style functions.  For example,
@code{_go32_dpmi_allocate_dos_memory} stores a value in pm_selector that
is only used by @code{_go32_dpmi_free_dos_memory}. 

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

@example
#include <dpmi.h>

int _go32_dpmi_allocate_dos_memory(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{Go32/DPMI Information}

Allocate a part of the conventional memory area (the first 640K).  Set
the @code{size} field of @var{info} to the number of paragraphs
requested (this is (size in bytes + 15)/16), then call.  The
@code{rm_segment} field of @var{info} contains the segment of the
allocated memory. 

The memory may be resized with @code{_go32_dpmi_resize_dos_memory} and
must be freed with @code{_go32_dpmi_free_dos_memory}. 

If there isn't enough memory in the system, the @code{size} field of
@var{info} has the largest available size, and an error is returned. 

@xref{dosmemput} @xref{dosmemget}

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
_go32_dpmi_seginfo info;
info.size = (want_size+15) / 16;
_go32_dpmi_allocate_dos_memory(&info);
dosmemput(buffer, want_size, info.rm_segment*16);
_go32_dpmi_free_dos_memory(&info);
@end example

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

@example
#include <dpmi.h>

int _go32_dpmi_allocate_iret_wrapper(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function creates a small assembler function that handles the
overhead of servicing an interrupt.  To use, put the address of your
servicing function in the @code{pm_offset} field of @var{info} and call
this function.  The @code{pm_field} will get replaced with the address
of the wrapper function, which you pass to both
@code{_go32_dpmi_set_protected_mode_interrupt_vector} and
@code{_go32_dpmi_free_iret_wrapper}. 

@xref{_go32_dpmi_set_protected_mode_interrupt_vector}
@xref{_go32_dpmi_free_iret_wrapper}

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
_go32_dpmi_seginfo info;
info.pm_offset = my_handler;
_go32_dpmi_allocate_iret_wrapper(&info);
_go32_dpmi_set_protected_mode_interrupt_handler(0x75, &info);
@dots{}
_go32_dpmi_free_iret_wrapper(&info);
@end example

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

@example
#include <dpmi.h>

int _go32_dpmi_allocate_real_mode_callback_iret(_go32_dpmi_seginfo *info, _go32_dpmi_registers *regs);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function allocates a "real-mode callback".  Fill in the
@code{pm_offset} field of @var{info} and call this function.  It will
fill in the @code{rm_segment} and @code{rm_offset} fields.  Any time a
real-mode program calls the real-mode address, your function gets
called.  The registers in affect will be stored in @var{regs}, which
should be a global, and will be passed to your function.  Any changes in
@var{regs} will be reflected back into real mode.  A wrapper will be
added to your function to simulate the effects of an @code{iret}
instruction, so this function is useful for trapping real-mode software
interrupts (like 0x1b - @kbd{Ctrl-Break} hit). 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
_go32_dpmi_registers regs;

my_handler(_go32_dpmi_registers *r)
@{
  r.d.eax = 4;
@}

setup()
@{
  _go32_dpmi_seginfo info;
  _go32_dpmi_seginfo old_vector;
  _go32_dpmi_get_real_mode_interrupt_vector(0x84, &old_vector);
  info.pm_offset = my_handler;
  _go32_dpmi_allocate_real_mode_callback_iret(&info, &regs);
  _go32_dpmi_set_real_mode_interrupt_vector(0x84, &info);
  do_stuff();
  _go32_dpmi_set_real_mode_interrupt_vector(0x84, &old_vector);
  _go32_dpmi_free_real_mode_callback(&info);
@}
@end example

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

@example
#include <dpmi.h>

int _go32_dpmi_allocate_real_mode_callback_retf(_go32_dpmi_seginfo *info, _go32_dpmi_registers *regs);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function allocates a "real-mode callback".  Fill in the
@code{pm_offset} field of @var{info} and call this function.  It will
fill in the @code{rm_segment} and @code{rm_offset} fields.  Any time a
real-mode program calls the real-mode address, your function gets
called.  The registers in affect will be stored in @var{regs}, which
should be a global, and will be passed to your function.  Any changes in
@var{regs} will be reflected back into real mode.  A wrapper will be
added to your function to simulate the effects of a far return, such
as the callback for the packet driver receiver.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}

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

@example
#include <dpmi.h>

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

@subheading Description

@xref{Go32/DPMI Information}

This function is used to chain a protected mode interrupt.  It will
build a suitable wrapper that will call your function and then jump to
the next handler.  Your function need not perform any special handling. 

@strong{Warning!} Because of the way DPMI works, you may @emph{not}
@code{longjmp} out of an interrupt handler or perform any system calls
(such as @code{printf}) from within an interrupt handler. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@xref{_go32_dpmi_set_protected_mode_interrupt_vector}

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

@example
#include <dpmi.h>

int _go32_dpmi_free_dos_memory(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function frees the conventional memory allocated by
@code{_go32_dpmi_allocate_real_mode_memory}.  You should pass it the
same structure as was used to allocate it. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
_go32_dpmi_seginfo info;
info.size = 100;
_go32_dpmi_allocate_dos_memory(&info);
_go32_dpmi_free_dos_memory(&info);
@end example

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

@example
#include <dpmi.h>

int _go32_dpmi_free_iret_wrapper(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function frees the memory used by the wrapper created by
@code{_go32_dpmi_allocate_iret_wrapper}.  You should not free a wrapper
that is still in use. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@xref{_go32_dpmi_allocate_iret_wrapper}

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

@example
#include <dpmi.h>

int _go32_dpmi_free_real_mode_callback(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{Go32/DPMI Information}

This function frees the real-mode callbacks and wrappers allocated by
@code{_go32_dpmi_allocate_real_mode_callback_iret} and
@code{_go32_dpmi_allocate_real_mode_callback_retf}. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}

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

@example
#include <dpmi.h

int _go32_dpmi_get_free_memory_information(_go32_dpmi_meminfo *info);
@end example

@subheading Description

This function fills in the following structure:

@example
typedef struct @{
  u_long available_memory;
  u_long available_pages;
  u_long available_lockable_pages;
  u_long linear_space;
  u_long unlocked_pages;
  u_long available_physical_pages;
  u_long total_physical_pages;
  u_long free_linear_space;
  u_long max_pages_in_paging_file;
  u_long reserved[3];
@} _go32_dpmi_meminfo;
@end example

The only field that is guaranteed to have useful data is
@code{available_memory}.  Any unavailable field has -1 in it. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@example
int phys_mem_left()
@{
  _go32_dpmi_meminfo info;
  _go32_dpmi_get_free_memory_information(&info);
  if (info.available_physical_pages != -1)
    return info.available_physical_pages * 4096;
  return info.available_memory;
@}
@end example

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

@example
#include <dpmi.h>

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

@subheading Description

@xref{Go32/DPMI Information}

This function puts the selector and offset of the specified interrupt
vector into the @code{pm_selector} and @code{pm_offset} fields of
@var{info}.  This structure can be saved and later passed to
@code{_go32_dpmi_get_protected_mode_interrupt_vector} to restore
a vector.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@xref{_go32_dpmi_set_protected_mode_interrupt_vector}

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

@example
#include <dpmi.h>

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

@subheading Description

@xref{Go32/DPMI Information}

This function fills in the @code{rm_segment} and @code{rm_offset} fields
of @var{info} with the address of the specified real-mode interrupt
vector. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}

@c ----------------------------------------------------------------------
@node _go32_dpmi_remaining_physical_memory, dpmi
@heading @code{_go32_dpmi_remaining_physical_memory}