Subsections

- 1 Introduction
- 2 Protected mode memory organization
  - 1 What is DPMI
  - 2 Selectors and descriptors
  - 3 FPC specialities
  - 4 DOS memory access
  - 5 I/O port access
  - 6 Processor access
  - 7 Interrupt redirection
  - 8 Handling interrupts with DPMI
  - 9 Protected mode interrupts vs. Real mode interrupts
  - 10 Creating own interrupt handlers
  - 11 Disabling interrupts
  - 12 Hardware interrupts
  - 13 Software interrupts
  - 14 Real mode callbacks
- 3 Types, Variables and Constants
  - 1 Constants
  - 2 Predefined types
  - 3 Variables.
- 4 Functions and Procedures
  - 1 allocate_ldt_descriptors
  - 2 allocate_memory_block
  - 3 copyfromdos
  - 4 copytodos
  - 5 create_code_segment_alias_descriptor
  - 6 disable
  - 7 dosmemfillchar
  - 8 dosmemfillword
  - 9 dosmemget
  - 10 dosmemmove
  - 11 dosmemput
  - 12 enable
  - 13 free_ldt_descriptor
  - 14 free_memory_block
  - 15 free_rm_callback
  - 16 get_cs
  - 17 get_descriptor_access_rights
  - 18 get_ds
  - 19 get_linear_addr
  - 20 get_meminfo
  - 21 get_next_selector_increment_value
  - 22 get_page_size
  - 23 get_pm_interrupt
  - 24 get_rm_callback
  - 25 get_rm_interrupt
  - 26 get_run_mode
  - 27 get_segment_base_address
  - 28 get_segment_limit
  - 29 get_ss
  - 30 global_dos_alloc
  - 31 global_dos_free
  - 32 inportb
  - 33 inportl
  - 34 inportw
  - 35 lock_code
  - 36 lock_data
  - 37 lock_linear_region
  - 38 outportb
  - 39 outportl
  - 40 outportw
  - 41 realintr
  - 42 seg_fillchar
  - 43 seg_fillword
  - 44 segment_to_descriptor
  - 45 seg_move
  - 46 set_descriptor_access_rights
  - 47 set_pm_interrupt
  - 48 set_rm_interrupt
  - 49 set_segment_base_address
  - 50 set_segment_limit
  - 51 tb_size
  - 52 transfer_buffer
  - 53 unlock_code
  - 54 unlock_data
  - 55 unlock_linear_region

# 7 The GO32 unit

This chapter of the documentation describe the GO32 unit for the Free Pascal compiler under DOS. It was donated by Thomas Schatzl (tom_at_work@geocities.com), for which my thanks. This unit was first written for DOS by Florian Klaempfl. This chapter is divided in four sections. The first two sections are an introduction to the GO32 unit. The third section lists the pre-defined constants, types and variables. The last section describes the functions which appear in the interface part of the GO32 unit.

# 1 Introduction

These docs contain information about the GO32 unit. Only the GO32V2 DPMI mode is discussed by me here due to the fact that new applications shouldn't be created with the older GO32V1 model. The go32v2 version is much more advanced and better. Additionally a lot of functions only work in DPMI mode anyway. I hope the following explanations and introductions aren't too confusing at all. If you notice an error or bug send it to the FPC mailing list or directly to me. So let's get started and happy and error free coding I wish you.... Thomas Schatzl, 25. August 1998

# 2 Protected mode memory organization

## 1 What is DPMI

The DOS Protected Mode Interface helps you with various aspects of protected mode programming. These are roughly divided into descriptor handling, access to DOS memory, management of interrupts and exceptions, calls to real mode functions and other stuff. Additionally it automatically provides swapping to disk for memory intensive applications. A DPMI host (either a Windows DOS box or CWSDPMI.EXE) provides these functions for your programs.

## 2 Selectors and descriptors

Descriptors are a bit like real mode segments; they describe (as the name implies) a memory area in protected mode. A descriptor contains information about segment length, its base address and the attributes of it (i.e. type, access rights, ...). These descriptors are stored internally in a so-called descriptor table, which is basically an array of such descriptors. Selectors are roughly an index into this table. Because these 'segments' can be up to 4 GB in size, 32 bits aren't sufficient anymore to describe a single memory location like in real mode. 48 bits are now needed to do this, a 32 bit address and a 16 bit sized selector. The GO32 unit provides the tseginfo record to store such a pointer. But due to the fact that most of the time data is stored and accessed in the %ds selector, FPC assumes that all pointers point to a memory location of this selector. So a single pointer is still only 32 bits in size. This value represents the offset from the data segment base address to this memory location.

## 3 FPC specialities

The %ds and %es selector MUST always contain the same value or some system routines may crash when called. The %fs selector is preloaded with the DOSMEMSELECTOR variable at startup, and it MUST be restored after use, because again FPC relys on this for some functions. Luckily we asm programmers can still use the %gs selector for our own purposes, but for how long ? See also: get_cs, get_ds, gett_ss, allocate_ldt_descriptors, free_ldt_descriptor, segment_to_descriptor, get_next_selector_increment_value, get_segment_base_address, set_segment_base_address, set_segment_limit, create_code_segment_alias_descriptor

## 4 DOS memory access

DOS memory is accessed by the predefined `dosmemselector` selector; the GO32 unit additionally provides some functions to help you with standard tasks, like copying memory from heap to DOS memory and the likes. Because of this it is strongly recommened to use them, but you are still free to use the provided standard memory accessing functions which use 48 bit pointers. The third, but only thought for compatibility purposes, is using the `mem[]`-arrays. These arrays map the whole 1 Mb DOS space. They shouldn't be used within new programs. To convert a segment:offset real mode address to a protected mode linear address you have to multiply the segment by 16 and add its offset. This linear address can be used in combination with the DOSMEMSELECTOR variable. See also: dosmemget, dosmemput, dosmemmove, dosmemfillchar, dosmemfillword, mem[]-arrays, seg_move, seg_fillchar, seg_fillword.

## 5 I/O port access

The I/O port access is done via the various inportb, outportb functions which are available. Additionally Free Pascal supports the Turbo Pascal PORT[]-arrays but it is by no means recommened to use them, because they're only for compatibility purposes. See also: outportb, inportb, PORT[]-arrays

## 6 Processor access

These are some functions to access various segment registers (%cs, %ds, %ss) which makes your work a bit easier. See also: get_cs, get_ds, get_ss

## 7 Interrupt redirection

Interrupts are program interruption requests, which in one or another way get to the processor; there's a distinction between software and hardware interrupts. The former are explicitely called by an 'int' instruction and are a bit comparable to normal functions. Hardware interrupts come from external devices like the keyboard or mouse. Functions that handle hardware interrupts are called handlers.

## 8 Handling interrupts with DPMI

The interrupt functions are real-mode procedures; they normally can't be called in protected mode without the risk of an protection fault. So the DPMI host creates an interrupt descriptor table for the application. Initially all software interrupts (except for int 31h, 2Fh and 21h function 4Ch) or external hardware interrupts are simply directed to a handler that reflects the interrupt in real-mode, i.e. the DPMI host's default handlers switch the CPU to real-mode, issue the interrupt and switch back to protected mode. The contents of general registers and flags are passed to the real mode handler and the modified registers and flags are returned to the protected mode handler. Segment registers and stack pointer are not passed between modes.

## 9 Protected mode interrupts vs. Real mode interrupts

As mentioned before, there's a distinction between real mode interrupts and protected mode interrupts; the latter are protected mode programs, while the former must be real mode programs. To call a protected mode interrupt handler, an assembly 'int' call must be issued, while the other is called via the realintr() or intr() function. Consequently, a real mode interrupt then must either reside in DOS memory (<1MB) or the application must allocate a real mode callback address via the get_rm_callback() function.

## 10 Creating own interrupt handlers

Interrupt redirection with FPC pascal is done via the set_pm_interrupt() for protected mode interrupts or via the set_rm_interrupt() for real mode interrupts.

## 11 Disabling interrupts

The GO32 unit provides the two procedures disable() and enable() to disable and enable all interrupts.

## 12 Hardware interrupts

Hardware interrupts are generated by hardware devices when something unusual happens; this could be a keypress or a mouse move or any other action. This is done to minimize CPU time, else the CPU would have to check all installed hardware for data in a big loop (this method is called 'polling') and this would take much time. A standard IBM-PC has two interrupt controllers, that are responsible for these hardware interrupts: both allow up to 8 different interrupt sources (IRQs, interrupt requests). The second controller is connected to the first through IRQ 2 for compatibility reasons, e.g. if controller 1 gets an IRQ 2, he hands the IRQ over to controller 2. Because of this up to 15 different hardware interrupt sources can be handled. IRQ 0 through IRQ 7 are mapped to interrupts 8h to Fh and the second controller (IRQ 8 to 15) is mapped to interrupt 70h to 77h. All of the code and data touched by these handlers MUST be locked (via the various locking functions) to avoid page faults at interrupt time. Because hardware interrupts are called (as in real mode) with interrupts disabled, the handler has to enable them before it returns to normal program execution. Additionally a hardware interrupt must send an EOI (end of interrupt) command to the responsible controller; this is acomplished by sending the value 20h to port 20h (for the first controller) or A0h (for the second controller). The following example shows how to redirect the keyboard interrupt.

Example

      {$ASMMODE ATT}
      {$MODE FPC}

      uses
      	crt,
      	go32;

      const
      	kbdint = $9;

      var
      	oldint9_handler : tseginfo;
      	newint9_handler : tseginfo;

      	clickproc : pointer;
      	backupDS : Word; external name '___v2prt0_ds_alias';

      procedure int9_handler; assembler;
      asm
      	cli
      	pushl %ds
      	pushl %es
      	pushl %fs
      	pushl %gs
      	pushal
      	movw %cs:backupDS, %ax
      	movw %ax, %ds
      	movw %ax, %es
      	movw dosmemselector, %ax
      	movw %ax, %fs
      	call *clickproc
      	popal
      	popl %gs
      	popl %fs
      	popl %es
      	popl %ds
      	ljmp %cs:oldint9_handler
      end;
      procedure int9_dummy; begin end;

      procedure clicker;
      begin
      	sound(500); delay(10); nosound;
      end;
      procedure clicker_dummy; begin end;

      procedure install_click;
      begin
      	clickproc := @clicker;
      	lock_data(clickproc, sizeof(clickproc));
      	lock_data(dosmemselector, sizeof(dosmemselector));

      	lock_code(@clicker,
      		longint(@clicker_dummy) - longint(@clicker));
      	lock_code(@int9_handler,
      		longint(@int9_dummy)-longint(@int9_handler));
      	newint9_handler.offset := @int9_handler;
      	newint9_handler.segment := get_cs;
      	get_pm_interrupt(kbdint, oldint9_handler);
      	set_pm_interrupt(kbdint, newint9_handler);
      end;

      procedure remove_click;
      begin
      	set_pm_interrupt(kbdint, oldint9_handler);
      	unlock_data(dosmemselector, sizeof(dosmemselector));
      	unlock_data(clickproc, sizeof(clickproc));

      	unlock_code(@clicker,
      		longint(@clicker_dummy)-longint(@clicker));
      	unlock_code(@int9_handler,
      		longint(@int9_dummy)-longint(@int9_handler));
      end;

      var
      	ch : char;

      begin
      	install_click;
      	Writeln('Enter any message. Press return when finished');
      	while (ch <> #13) do begin
      		ch := readkey; write(ch);
      	end;
      	remove_click;
      end.

## 13 Software interrupts

Ordinarily, a handler installed with set_pm_interrupt only services software interrupts that are executed in protected mode; real mode software interrupts can be redirected by set_rm_interrupt. See also set_rm_interrupt, get_rm_interrupt, set_pm_interrupt, get_pm_interrupt, lock_data, lock_code, enable, disable, outportb Executing software interrupts Simply execute a realintr() call with the desired interrupt number and the supplied register data structure. But some of these interrupts require you to supply them a pointer to a buffer where they can store data to or obtain data from in memory. These interrupts are real mode functions and so they only can access the first Mb of linear address space, not FPC's data segment. For this reason FPC supplies a pre-initialized DOS memory location within the GO32 unit. This buffer is internally used for DOS functions too and so it's contents may change when calling other procedures. It's size can be obtained with tb_size and it's linear address via transfer_buffer. Another way is to allocate a completely new DOS memory area via the global_dos_alloc function for your use and supply its real mode address. See also: tb_size, transfer_buffer. global_dos_alloc, global_dos_free, realintr The following examples illustrate the use of software interrupts.

Example

      uses
      	go32;

      var
      	r : trealregs;

      begin
      	r.ah := $30;
      	r.al := $01;
      	realintr($21, r);
      	Writeln('DOS v', r.al,'.',r.ah, ' detected');
      end.

Example

      uses
      	crt,
      	go32;

      var
      	r : trealregs;
      	axreg : Word;

      	oldint21h : tseginfo;
      	newint21h : tseginfo;
      procedure int21h_handler; assembler;
      asm
      	cmpw $0x3001, %ax
      	jne .LCallOld
      	movw $0x3112, %ax
      	iret

      .LCallOld:
      	ljmp %cs:oldint21h
      end;

      procedure resume;
      begin
      	Writeln;
      	Write('-- press any key to resume --'); readkey;
      	gotoxy(1, wherey); clreol;
      end;

      begin
      	clrscr;
      	Writeln('Executing real mode interrupt');
      	resume;
      	r.ah := $30; r.al := $01;  realintr($21, r);
      	Writeln('DOS v', r.al,'.',r.ah, ' detected');
      	resume;
      	Writeln('Executing protected mode interrupt without our own',
      		' handler');
      	Writeln;
      	asm
      		movb $0x30, %ah
      		movb $0x01, %al
      		int $0x21
      		movw %ax, axreg
      	end;
      	Writeln('DOS v', r.al,'.',r.ah, ' detected');
      	resume;
      	Writeln('As you can see the DPMI hosts default protected mode',
      		'handler');
      	Writeln('simply redirects it to the real mode handler');
      	resume;
      	Writeln('Now exchanging the protected mode interrupt with our ',
      		'own handler');
      	resume;

      	newint21h.offset := @int21h_handler;
      	newint21h.segment := get_cs;
      	get_pm_interrupt($21, oldint21h);
      	set_pm_interrupt($21, newint21h);

      	Writeln('Executing real mode interrupt again');
      	resume;
      	r.ah := $30; r.al := $01; realintr($21, r);
      	Writeln('DOS v', r.al,'.',r.ah, ' detected');
      	Writeln;
      	Writeln('See, it didn''t change in any way.');
      	resume;
      	Writeln('Now calling protected mode interrupt');
      	resume;
      	asm
      		movb $0x30, %ah
      		movb $0x01, %al
      		int $0x21
      		movw %ax, axreg
      	end;
      	Writeln('DOS v', lo(axreg),'.',hi(axreg), ' detected');
      	Writeln;
      	Writeln('Now you can see that there''s a distinction between ',
      		'the two ways of calling interrupts...');
      	set_pm_interrupt($21, oldint21h);
      end.

## 14 Real mode callbacks

The callback mechanism can be thought of as the converse of calling a real mode procedure (i.e. interrupt), which allows your program to pass information to a real mode program, or obtain services from it in a manner that's transparent to the real mode program. In order to make a real mode callback available, you must first get the real mode callback address of your procedure and the selector and offset of a register data structure. This real mode callback address (this is a segment:offset address) can be passed to a real mode program via a software interrupt, a DOS memory block or any other convenient mechanism. When the real mode program calls the callback (via a far call), the DPMI host saves the registers contents in the supplied register data structure, switches into protected mode, and enters the callback routine with the following settings:

- interrupts disabled
- `%CS:%EIP` = 48 bit pointer specified in the original call to get_rm_callback
- `%DS:%ESI` = 48 bit pointer to to real mode `SS:SP`
- `%ES:%EDI` = 48 bit pointer of real mode register data structure.
- `%SS:%ESP` = locked protected mode stack
- All other registers undefined

The callback procedure can then extract its parameters from the real mode register data structure and/or copy parameters from the real mode stack to the protected mode stack. Recall that the segment register fields of the real mode register data structure contain segment or paragraph addresses that are not valid in protected mode. Far pointers passed in the real mode register data structure must be translated to virtual addresses before they can be used with a protected mode program. The callback procedure exits by executing an IRET with the address of the real mode register data structure in `%ES:%EDI`, passing information back to the real mode caller by modifying the contents of the real mode register data structure and/or manipulating the contents of the real mode stack. The callback procedure is responsible for setting the proper address for resumption of real mode execution into the real mode register data structure; typically, this is accomplished by extracting the return address from the real mode stack and placing it into the `%CS:%EIP` fields of the real mode register data structure. After the IRET, the DPMI host switches the CPU back into real mode, loads ALL registers with the contents of the real mode register data structure, and finally returns control to the real mode program. All variables and code touched by the callback procedure MUST be locked to prevent page faults. See also: get_rm_callback, free_rm_callback, lock_code, lock_data

# 3 Types, Variables and Constants

## 1 Constants

### 1 Constants returned by get_run_mode

Tells you under what memory environment (e.g. memory manager) the program currently runs.

    rm_unknown = 0; { unknown }
    rm_raw     = 1; { raw (without HIMEM) }
    rm_xms     = 2; { XMS (for example with HIMEM, without EMM386) }
    rm_vcpi    = 3; { VCPI (for example HIMEM and EMM386) }
    rm_dpmi    = 4; { DPMI (for example \dos box or 386Max) }

Note: GO32V2 always creates DPMI programs, so you need a suitable DPMI host like CWSDPMI.EXE or a Windows DOS box. So you don't need to check it, these constants are only useful in GO32V1 mode.

### 2 Processor flags constants

They are provided for a simple check with the flags identifier in the trealregs type. To check a single flag, simply do an AND operation with the flag you want to check. It's set if the result is the same as the flag value.

    const carryflag = $001;
    parityflag      = $004;
    auxcarryflag    = $010;
    zeroflag        = $040;
    signflag        = $080;
    trapflag        = $100;
    interruptflag   = $200;
    directionflag   = $400;
    overflowflag    = $800;

## 2 Predefined types

    type tmeminfo = record
                available_memory : Longint;
                available_pages : Longint;
                available_lockable_pages : Longint;
                linear_space : Longint;
                unlocked_pages : Longint;
                available_physical_pages : Longint;
                total_physical_pages : Longint;
                free_linear_space : Longint;
                max_pages_in_paging_file : Longint;
                reserved : array[0..2] of Longint;
       end;

Holds information about the memory allocation, etc.

Table: Record description
Record entry | Description
`available_memory` | Largest available free block in bytes.
`available_pages` | Maximum unlocked page allocation in pages
`available_lockable_pages` | Maximum locked page allocation in pages.
`linear_space` | Linear address space size in pages.
`unlocked_pages` | Total number of unlocked pages.
`available_physical_pages` | Total number of free pages.
`total_physical_pages` | Total number of physical pages.
`free_linear_space` | Free linear address space in pages.
`max_pages_in_paging_file` | Size of paging file/partition in pages.

NOTE: The value of a field is -1 (0ffffffffh) if the value is unknown, it's only guaranteed, that `available_memory` contains a valid value. The size of the pages can be determined by the get_page_size() function.

    type
    trealregs = record
      case Integer of
        1: { 32-bit }
          (EDI, ESI, EBP, Res, EBX, EDX, ECX, EAX: Longint;
           Flags, ES, DS, FS, GS, IP, CS, SP, SS: Word);
        2: { 16-bit }
          (DI, DI2, SI, SI2, BP, BP2, R1, R2: Word;
           BX, BX2, DX, DX2, CX, CX2, AX, AX2: Word);
        3: { 8-bit }
          (stuff: array[1..4] of Longint;
           BL, BH, BL2, BH2, DL, DH, DL2, DH2, CL,
           CH, CL2, CH2, AL, AH, AL2, AH2: Byte);
        4: { Compat }
          (RealEDI, RealESI, RealEBP, RealRES, RealEBX,
           RealEDX, RealECX, RealEAX: Longint;
           RealFlags, RealES, RealDS, RealFS, RealGS,
           RealIP, RealCS, RealSP, RealSS: Word);
        end;
        registers = trealregs;

These two types contain the data structure to pass register values to a interrupt handler or real mode callback.

    type tseginfo = record
                 offset : Pointer; segment : Word; end;

This record is used to store a full 48-bit pointer. This may be either a protected mode selector:offset address or in real mode a segment:offset address, depending on application. See also: Selectors and descriptors, DOS memory access, Interrupt redirection

## 3 Variables.

    var dosmemselector : Word;

Selector to the DOS memory. The whole DOS memory is automatically mapped to this single descriptor at startup. This selector is the recommened way to access DOS memory.

      var int31error : Word;

This variable holds the result of a DPMI interrupt call. Any nonzero value must be treated as a critical failure.

# 4 Functions and Procedures

##
1 allocate_ldt_descriptors

Declaration
  `Function allocate_ldt_descriptors (count : Word) : Word;`

  ``

Description
  Allocates a number of new descriptors. Parameters:
  count:
    specifies the number of requested unique descriptors.
  Return value: The base selector. Notes: The descriptors allocated must be initialized by the application with other function calls. This function returns descriptors with a limit and size value set to zero. If more than one descriptor was requested, the function returns a base selector referencing the first of a contiguous array of descriptors. The selector values for subsequent descriptors in the array can be calculated by adding the value returned by the get_next_selector_increment_value function.

Errors
  Check the `int31error` variable.
See also

  free_ldt_descriptor, get_next_selector_increment_value, segment_to_descriptor, create_code_segment_alias_descriptor, set_segment_limit, set_segment_base_address

Example

      {$mode delphi}
      uses
      	crt,
      	go32;

      const
      	maxx = 80;
      	maxy = 25;
      	bytespercell = 2;
      	screensize = maxx * maxy * bytespercell;

      	linB8000 = $B800 * 16;

      type
      	string80 = string[80];

      var
      	text_save : array[0..screensize-1] of byte;
      	text_oldx, text_oldy : Word;

      	text_sel : Word;

      procedure status(s : string80);
      begin
           gotoxy(1, 1); clreol; write(s); readkey;
      end;

      procedure selinfo(sel : Word);
      begin
           gotoxy(1, 24);
           clreol; writeln('Descriptor base address : $',
           	hexstr(get_segment_base_address(sel), 8));
           clreol; write('Descriptor limit : ', get_segment_limit(sel));
      end;

      function makechar(ch : char; color : byte) : Word;
      begin
           result := byte(ch) or (color shl 8);
      end;

      begin
           seg_move(dosmemselector, linB8000, get_ds, longint(@text_save),
           	screensize);
           text_oldx := wherex; text_oldy := wherey;
           seg_fillword(dosmemselector, linB8000, screensize div 2,
           	makechar(' ', Black or (Black shl 4)));
           status('Creating selector ''text_sel'' to a part of ' +
           	'text screen memory');
           text_sel := allocate_ldt_descriptors(1);
           set_segment_base_address(text_sel,
           	linB8000 + bytespercell * maxx * 1);
           set_segment_limit(text_sel, screensize - 1 - bytespercell *
           	maxx * 3);
           selinfo(text_sel);

           status('and clearing entire memory selected by ''text_sel''' +
           	' descriptor');
           seg_fillword(text_sel, 0, (get_segment_limit(text_sel)+1) div 2,
           	makechar(' ', LightBlue shl 4));

           status('Notice that only the memory described by the' +
           	' descriptor changed, nothing else');

           status('Now reducing it''s limit and base and setting it''s ' +
           	'described memory');
           set_segment_base_address(text_sel,
           	get_segment_base_address(text_sel) + bytespercell * maxx);
           set_segment_limit(text_sel,
           	get_segment_limit(text_sel) - bytespercell * maxx * 2);
           selinfo(text_sel);
           status('Notice that the base addr increased by one line but ' +
           	'the limit decreased by 2 lines');
           status('This should give you the hint that the limit is ' +
           	'relative to the base');
           seg_fillword(text_sel, 0, (get_segment_limit(text_sel)+1) div 2,
           	makechar(#176, LightMagenta or Brown shl 4));

           status('Now let''s get crazy and copy 10 lines of data from ' +
           	'the previously saved screen');
           seg_move(get_ds, longint(@text_save), text_sel,
           	maxx * bytespercell * 2, maxx * bytespercell * 10);

           status('At last freeing the descriptor and restoring the old '+
           	' screen contents..');
           status('I hope this little program may give you some hints on '+
           	'working with descriptors');
           free_ldt_descriptor(text_sel);
           seg_move(get_ds, longint(@text_save), dosmemselector,
           	linB8000, screensize);
           gotoxy(text_oldx, text_oldy);
      end.

##
2 allocate_memory_block

Declaration
  `Function allocate_memory_block (size:Longint) : Longint;`

  ``

Description
  Allocates a block of linear memory. Parameters:
  size:
    Size of requested linear memory block in bytes.
  Returned values: blockhandle - the memory handle to this memory block. Linear address of the requested memory. Notes: WARNING: According to my DPMI docs this function is not implemented correctly. Normally you should also get a blockhandle to this block after successful operation. This handle can then be used to free the memory block afterwards or use this handle for other purposes. Since the function isn't implemented correctly, and doesn't return a blockhandle, the block can't be deallocated and is hence unusuable ! This function doesn't allocate any descriptors for this block, it's the applications resposibility to allocate and initialize for accessing this memory.

Errors
  Check the `int31error` variable.
See also
  free_memory_block

##
3 copyfromdos

Declaration
  `Procedure copyfromdos (var addr; len : Longint);`

  ``

Description

  Copies data from the pre-allocated DOS memory transfer buffer to the heap. Parameters:

  addr:
    data to copy to.
  len:
    number of bytes to copy to heap.
  Notes: Can only be used in conjunction with the DOS memory transfer buffer.

Errors
  Check the `int31error` variable.
See also
  tb_size, transfer_buffer, copytodos

##
4 copytodos

Declaration
  `Procedure copytodos (var addr; len : Longint);`

  ``

Description
  Copies data from heap to the pre-allocated DOS memory buffer. Parameters:
  addr:
    data to copy from.
  len:
    number of bytes to copy to DOS memory buffer.
  Notes: This function fails if you try to copy more bytes than the transfer buffer is in size. It can only be used in conjunction with the transfer buffer.

Errors
  Check the `int31error` variable.
See also
  tb_size, transfer_buffer, copyfromdos

##
5 create_code_segment_alias_descriptor

Declaration
  `Function create_code_segment_alias_descriptor (seg : Word) : Word;`

  ``

Description

  Creates a new descriptor that has the same base and limit as the specified descriptor. Parameters:

  seg:
    Descriptor.
  Return values: The data selector (alias). Notes: In effect, the function returns a copy of the descriptor. The descriptor alias returned by this function will not track changes to the original descriptor. In other words, if an alias is created with this function, and the base or limit of the original segment is then changed, the two descriptors will no longer map the same memory.

Errors
  Check the `int31error` variable.
See also

  allocate_ldt_descriptors, set_segment_limit, set_segment_base_address

##
6 disable

Declaration
  `Procedure disable ;`

  ``

Description
  Disables all hardware interrupts by execution a CLI instruction. Parameters: None.

Errors
  None.
See also
  enable

##
7 dosmemfillchar

Declaration
  `Procedure dosmemfillchar (seg, ofs : Word; count : Longint; c : char);`

  ``

Description
  Sets a region of DOS memory to a specific byte value. Parameters:
  seg:
    real mode segment.
  ofs:
    real mode offset.
  count:
    number of bytes to set.
  c:
    value to set memory to.
  Notes: No range check is performed.

Errors
  None.
See also

  dosmemput, dosmemget, dosmemmovedosmemmove, dosmemfillword, seg_move, seg_fillchar, seg_fillword

Example

      uses
      	crt,
      	go32;

      const
      	columns = 80;
      	rows = 25;
      	screensize = rows*columns*2;

      	text = '! Hello world !';

      var
      	textofs : Longint;
      	save_screen : array[0..screensize-1] of byte;
          curx, cury : Integer;

      begin
      	randomize;
      	dosmemget($B800, 0, save_screen, screensize);
      	curx := wherex; cury := wherey;
      	gotoxy(1, 1); Write(text);
      	textofs := screensize + length(text)*2;
      	dosmemmove($B800, 0, $B800, textofs, length(text)*2);
      	dosmemfillchar($B800, 0, screensize, #0);
      	while (not keypressed) do begin
      		dosmemfillchar($B800, textofs + random(length(text))*2 + 1,
      			1, char(random(255)));
      		dosmemmove($B800, textofs, $B800,
      			random(columns)*2+random(rows)*columns*2,
      			length(text)*2);
      		delay(1);
      	end;
      	readkey;
      	readkey;
      	dosmemput($B800, 0, save_screen, screensize);
      	gotoxy(curx, cury);
      end.

##
8 dosmemfillword

Declaration
  `Procedure dosmemfillword (seg,ofs : Word; count : Longint; w : Word);`

  ``

Description
  Sets a region of DOS memory to a specific word value. Parameters:
  seg:
    real mode segment.
  ofs:
    real mode offset.
  count:
    number of words to set.
  w:
    value to set memory to.
  Notes: No range check is performed.

Errors
  None.
See also

  dosmemput, dosmemget, dosmemmove, dosmemfillchar, seg_move, seg_fillchar, seg_fillword

##
9 dosmemget

Declaration
  `Procedure dosmemget (seg : Word; ofs : Word; var data; count : Longint);`

  ``

Description
  Copies data from the DOS memory onto the heap. Parameters:
  seg:
    source real mode segment.
  ofs:
    source real mode offset.
  data:
    destination.
  count:
    number of bytes to copy.
  Notes: No range checking is performed.

Errors
  None.
See also
  dosmemput, dosmemmove, dosmemfillchar, dosmemfillword, seg_move, seg_fillchar, seg_fillword

For an example, see global_dos_alloc.

##
10 dosmemmove

Declaration
  `Procedure dosmemmove (sseg, sofs, dseg, dofs : Word; count : Longint);`

  ``

Description
  Copies count bytes of data between two DOS real mode memory locations. Parameters:
  sseg:
    source real mode segment.
  sofs:
    source real mode offset.
  dseg:
    destination real mode segment.
  dofs:
    destination real mode offset.
  count:
    number of bytes to copy.
  Notes: No range check is performed in any way.

Errors
  None.
See also
  dosmemput, dosmemget, dosmemfillchar, dosmemfillword seg_move, seg_fillchar, seg_fillword

For an example, see seg_fillchar.

##
11 dosmemput

Declaration
  `Procedure dosmemput (seg : Word; ofs : Word; var data; count : Longint);`

  ``

Description
  Copies heap data to DOS real mode memory. Parameters:
  seg:
    destination real mode segment.
  ofs:
    destination real mode offset.
  data:
    source.
  count:
    number of bytes to copy.
  Notes: No range checking is performed.

Errors
  None.
See also
  dosmemget, dosmemmove, dosmemfillchar, dosmemfillword, seg_move, seg_fillchar, seg_fillword

For an example, see global_dos_alloc.

##
12 enable

Declaration
  `Procedure enable ;`

  ``

Description

  Enables all hardware interrupts by executing a STI instruction. Parameters: None.

Errors
  None.
See also
  disable

##
13 free_ldt_descriptor

Declaration
  `Function free_ldt_descriptor (des : Word) : boolean;`

  ``

Description
  Frees a previously allocated descriptor. Parameters:
  des:
    The descriptor to be freed.
  Return value: `True` if successful, `False` otherwise. Notes: After this call this selector is invalid and must not be used for any memory operations anymore. Each descriptor allocated with allocate_ldt_descriptors must be freed individually with this function, even if it was previously allocated as a part of a contiguous array of descriptors.

Errors
  Check the `int31error` variable.
See also

  allocate_ldt_descriptors, get_next_selector_increment_value

For an example, see allocate_ldt_descriptors.

##
14 free_memory_block

Declaration
  `Function free_memory_block (blockhandle : Longint) : boolean;`

  ``

Description
  Frees a previously allocated memory block. Parameters:
    blockhandle: the handle to the memory area to free.
  Return value: `True` if successful, `false` otherwise. Notes: Frees memory that was previously allocated with allocate_memory_block . This function doesn't free any descriptors mapped to this block, it's the application's responsibility.

Errors
  Check `int31error` variable.
See also
  allocate_memory_block

##
15 free_rm_callback

Declaration
  `Function free_rm_callback (var intaddr : tseginfo) : boolean;`

  ``

Description

  Releases a real mode callback address that was previously allocated with the get_rm_callback function. Parameters:

  intaddr:
    real mode address buffer returned by get_rm_callback .
  Return values: `True` if successful, `False` if not

Errors
  Check the `int31error` variable.
See also

  set_rm_interrupt, get_rm_callback

For an example, see get_rm_callback.

##
16 get_cs

Declaration
  `Function get_cs : Word;`

  ``

Description

  Returns the cs selector. Parameters: None. Return values: The content of the cs segment register.

Errors
  None.
See also
  get_ds, get_ss

For an example, see set_pm_interrupt.

##
17 get_descriptor_access_rights

Declaration
  `Function get_descriptor_access_rights (d : Word) : Longint;`

  ``

Description
  Gets the access rights of a descriptor. Parameters:
    d selector to descriptor.
  Return value: Access rights bit field.

Errors
  Check the `int31error` variable.
See also

  set_descriptor_access_rights

##
18 get_ds

Declaration
  `Function get_ds : Word;`

  ``

Description
  Returns the ds selector. Parameters: None. Return values: The content of the ds segment register.

Errors
  None.
See also
  get_cs, get_ss

##
19 get_linear_addr

Declaration
  `Function get_linear_addr (phys_addr : Longint; size : Longint) : Longint;`

  ``

Description
  Converts a physical address into a linear address. Parameters:
  phys_addr:
    physical address of device.
  size:
    Size of region to map in bytes.
  Return value: Linear address that can be used to access the physical memory. Notes: It's the applications resposibility to allocate and set up a descriptor for access to the memory. This function shouldn't be used to map real mode addresses.

Errors
  Check the `int31error` variable.
See also

  allocate_ldt_descriptors, set_segment_limit, set_segment_base_address

##
20 get_meminfo

Declaration
  `Function get_meminfo (var meminfo : tmeminfo) : boolean;`

  ``

Description
  Returns information about the amount of available physical memory, linear address space, and disk space for page swapping. Parameters:
  meminfo:
    buffer to fill memory information into.
  Return values: Due to an implementation bug this function always returns `False`, but it always succeeds. Notes: Only the first field of the returned structure is guaranteed to contain a valid value. Any fields that are not supported by the DPMI host will be set by the host to `-1 (0FFFFFFFFH)` to indicate that the information is not available. The size of the pages used by the DPMI host can be obtained with the get_page_size function.

Errors
  Check the `int31error` variable.
See also
  get_page_size

Example

      uses
      	go32;

      var
      	meminfo : tmeminfo;

      begin
      	get_meminfo(meminfo);
      	if (int31error <> 0)  then begin
      		Writeln('Error getting DPMI memory information... Halting');
      		Writeln('DPMI error number : ', int31error);
      	end else begin
      		with meminfo do begin
      			Writeln('Largest available free block : ',
      				available_memory div 1024, ' kbytes');
      			if (available_pages <> -1) then
      				Writeln('Maximum available unlocked pages : ',
      					available_pages);
      			if (available_lockable_pages <> -1) then
      				Writeln('Maximum lockable available pages : ',
      					available_lockable_pages);
      			if (linear_space <> -1) then
      				Writeln('Linear address space size : ',
      					linear_space*get_page_size div 1024, ' kbytes');
      			if (unlocked_pages <> -1) then
      				Writeln('Total number of unlocked pages : ',
      					unlocked_pages);
      			if (available_physical_pages <> -1) then
      				Writeln('Total number of free pages : ',
      					available_physical_pages);
      			if (total_physical_pages <> -1) then
      				Writeln('Total number of physical pages : ',
      					total_physical_pages);
      			if (free_linear_space <> -1) then
      				Writeln('Free linear address space : ',
      					free_linear_space*get_page_size div 1024,
      					' kbytes');
      			if (max_pages_in_paging_file <> -1) then
      				Writeln('Maximum size of paging file : ',
      					max_pages_in_paging_file*get_page_size div 1024,
      					' kbytes');
      		end;
      	end;
      end.

##
21 get_next_selector_increment_value

Declaration
  `Function get_next_selector_increment_value : Word;`

  ``

Description
  Returns the selector increment value when allocating multiple subsequent descriptors via allocate_ldt_descriptors. Parameters: None. Return value: Selector increment value. Notes: Because allocate_ldt_descriptors only returns the selector for the first descriptor and so the value returned by this function can be used to calculate the selectors for subsequent descriptors in the array.

Errors
  Check the `int31error` variable.
See also
  allocate_ldt_descriptors, free_ldt_descriptor

##
22 get_page_size

Declaration
  `Function get_page_size : Longint;`

  ``

Description
  Returns the size of a single memory page. Return value: Size of a single page in bytes. Notes: The returned size is typically 4096 bytes.

Errors
  Check the `int31error` variable.
See also
  get_meminfo

For an example, see get_meminfo.

##
23 get_pm_interrupt

Declaration
  `Function get_pm_interrupt (vector : byte; var intaddr : tseginfo) : boolean;`

  ``

Description
  Returns the address of a current protected mode interrupt handler. Parameters:
  vector:
    interrupt handler number you want the address to.
  intaddr:
    buffer to store address.
  Return values: `True` if successful, `False` if not. Notes: The returned address is a protected mode selector:offset address.

Errors
  Check the `int31error` variable.
See also
  set_pm_interrupt, set_rm_interrupt, get_rm_interrupt

For an example, see set_pm_interrupt.

##
24 get_rm_callback

Declaration
  `Function get_rm_callback (pm_func : pointer; const reg : trealregs; var rmcb: tseginfo) : boolean;`

  ``

Description

  Returns a unique real mode `segment:offset` address, known as a "real mode callback," that will transfer control from real mode to a protected mode procedure. Parameters:

  pm_func:
    pointer to the protected mode callback function.
  reg:
    supplied registers structure.
  rmcb:
    buffer to real mode address of callback function.
  Return values: `True` if successful, otherwise `False`. Notes: Callback addresses obtained with this function can be passed by a protected mode program for example to an interrupt handler, device driver, or TSR, so that the real mode program can call procedures within the protected mode program or notify the protected mode program of an event. The contents of the supplied regs structure is not valid after function call, but only at the time of the actual callback.

Errors
  Check the `int31error` variable.
See also
  free_rm_callback

Example

      {$ASMMODE ATT}
      {$MODE FPC}

      uses
      	crt,
      	go32;

      const
      	mouseint = $33;

      var
      	mouse_regs    : trealregs; external name '___v2prt0_rmcb_regs';
      	mouse_seginfo : tseginfo;

      var
      	mouse_numbuttons : longint;

      	mouse_action : word;
      	mouse_x, mouse_y : Word;
      	mouse_b : Word;

      	userproc_installed : Longbool;
      	userproc_length : Longint;
      	userproc_proc : pointer;

      procedure callback_handler; assembler;
      asm
         pushw %ds
         pushl %eax
         movw %es, %ax
         movw %ax, %ds

         cmpl $1, USERPROC_INSTALLED
         jne .LNoCallback
         pushal
         movw DOSmemSELECTOR, %ax
         movw %ax, %fs
         call *USERPROC_PROC
         popal
      .LNoCallback:

         popl %eax
         popw %ds

         pushl %eax
         movl (%esi), %eax
         movl %eax, %es: 42(%edi)
         addw $4, %es:46(%edi)
         popl %eax
         iret
      end;
      procedure mouse_dummy; begin end;

      procedure textuserproc;
      begin
      	mouse_b := mouse_regs.bx;
      	mouse_x := (mouse_regs.cx shr 3) + 1;
      	mouse_y := (mouse_regs.dx shr 3) + 1;
      end;

      procedure install_mouse(userproc : pointer; userproclen : longint);
      var r : trealregs;
      begin
      	r.eax := $0; realintr(mouseint, r);
      	if (r.eax <> $FFFF) then begin
      		Writeln('No Microsoft compatible mouse found');
      		Writeln('A Microsoft compatible mouse driver is necessary ',
      			'to run this example');
      		halt;
      	end;
      	if (r.bx = $ffff) then mouse_numbuttons := 2
      	else mouse_numbuttons := r.bx;
      	Writeln(mouse_numbuttons, ' button Microsoft compatible mouse ',
      		' found.');
      	if (userproc <> nil) then begin
      		userproc_proc := userproc;
      		userproc_installed := true;
      		userproc_length := userproclen;
      		lock_code(userproc_proc, userproc_length);
      	end else begin
      		userproc_proc := nil;
      		userproc_length := 0;
      		userproc_installed := false;
      	end;
      	lock_data(mouse_x, sizeof(mouse_x));
      	lock_data(mouse_y, sizeof(mouse_y));
      	lock_data(mouse_b, sizeof(mouse_b));
      	lock_data(mouse_action, sizeof(mouse_action));

      	lock_data(userproc_installed, sizeof(userproc_installed));
      	lock_data(userproc_proc, sizeof(userproc_proc));

      	lock_data(mouse_regs, sizeof(mouse_regs));
      	lock_data(mouse_seginfo, sizeof(mouse_seginfo));
      	lock_code(@callback_handler,
      		longint(@mouse_dummy)-longint(@callback_handler));
      	get_rm_callback(@callback_handler, mouse_regs, mouse_seginfo);
      	r.eax := $0c; r.ecx := $7f;
      	r.edx := longint(mouse_seginfo.offset);
      	r.es := mouse_seginfo.segment;
      	realintr(mouseint, r);
      	r.eax := $01;
      	realintr(mouseint, r);
      end;

      procedure remove_mouse;
      var
      	r : trealregs;
      begin
      	r.eax := $02; realintr(mouseint, r);
      	r.eax := $0c; r.ecx := 0; r.edx := 0; r.es := 0;
      	realintr(mouseint, r);
      	free_rm_callback(mouse_seginfo);
      	if (userproc_installed) then begin
      		unlock_code(userproc_proc, userproc_length);
      		userproc_proc := nil;
      		userproc_length := 0;
      		userproc_installed := false;
      	end;
      	unlock_data(mouse_x, sizeof(mouse_x));
      	unlock_data(mouse_y, sizeof(mouse_y));
      	unlock_data(mouse_b, sizeof(mouse_b));
      	unlock_data(mouse_action, sizeof(mouse_action));

      	unlock_data(userproc_proc, sizeof(userproc_proc));
      	unlock_data(userproc_installed, sizeof(userproc_installed));

      	unlock_data(mouse_regs, sizeof(mouse_regs));
      	unlock_data(mouse_seginfo, sizeof(mouse_seginfo));
      	unlock_code(@callback_handler,
      		longint(@mouse_dummy)-longint(@callback_handler));
      	fillchar(mouse_seginfo, sizeof(mouse_seginfo), 0);
      end;

      begin
      	install_mouse(@textuserproc, 400);
      	Writeln('Press any key to exit...');
      	while (not keypressed) do begin
      		gotoxy(1, wherey);
      		write('MouseX : ', mouse_x:2, ' MouseY : ', mouse_y:2,
      			' Buttons : ', mouse_b:2);
      	end;
      	remove_mouse;
      end.

##
25 get_rm_interrupt

Declaration
  `Function get_rm_interrupt (vector : byte; var intaddr : tseginfo) : boolean;`

  ``

Description
  Returns the contents of the current machine's real mode interrupt vector for the specified interrupt. Parameters:
  vector:
    interrupt vector number.
  intaddr:
    buffer to store real mode `segment:offset` address.
  Return values: `True` if successful, `False` otherwise. Notes: The returned address is a real mode segment address, which isn't valid in protected mode.

Errors
  Check the `int31error` variable.
See also
  set_rm_interrupt, set_pm_interrupt, get_pm_interrupt

##
26 get_run_mode

Declaration
  `Function get_run_mode : Word;`

  ``

Description
  Returns the current mode your application runs with. Return values: One of the constants used by this function.

Errors
  None.
See also
  constants returned by get_run_mode

Example

      uses
      	go32;

      begin
      	case (get_run_mode) of
      		rm_unknown :
      			Writeln('Unknown environment found');
      		rm_raw     :
      			Writeln('You are currently running in raw mode ',
      				'(without HIMEM)');
      		rm_xms     :
      			Writeln('You are currently using HIMEM.SYS only');
      		rm_vcpi    :
      			Writeln('VCPI server detected. You''re using HIMEM and ',
      				'EMM386');
      		rm_dpmi    :
      			Writeln('DPMI detected. You''re using a DPMI host like ',
      				'a windows DOS box or CWSDPMI');
      	end;
      end.

##
27 get_segment_base_address

Declaration
  `Function get_segment_base_address (d : Word) : Longint;`

  ``

Description
  Returns the 32-bit linear base address from the descriptor table for the specified segment. Parameters:
  d:
    selector of the descriptor you want the base address of.
  Return values: Linear base address of specified descriptor.

Errors
  Check the `int31error` variable.
See also

  allocate_ldt_descriptors, set_segment_base_address, allocate_ldt_descriptors, set_segment_limit, get_segment_limit

For an example, see allocate_ldt_descriptors.

##
28 get_segment_limit

Declaration
  `Function get_segment_limit (d : Word) : Longint;`

  ``

Description
  Returns a descriptors segment limit. Parameters:
  d:
    selector.
  Return value: Limit of the descriptor in bytes.

Errors
  Returns zero if descriptor is invalid.
See also
  allocate_ldt_descriptors, set_segment_limit, set_segment_base_address, get_segment_base_address,

##
29 get_ss

Declaration
  `Function get_ss : Word;`

  ``

Description

  Returns the ss selector. Parameters: None. Return values: The content of the ss segment register.

Errors
  None.
See also
  get_ds, get_cs

##
30 global_dos_alloc

Declaration
  `Function global_dos_alloc (bytes : Longint) : Longint;`

  ``

Description
  Allocates a block of DOS real mode memory. Parameters:
  bytes:
    size of requested real mode memory.
  Return values: The low word of the returned value contains the selector to the allocated DOS memory block, the high word the corresponding real mode segment value. The offset value is always zero. This function allocates memory from DOS memory pool, i.e. memory below the 1 MB boundary that is controlled by DOS. Such memory blocks are typically used to exchange data with real mode programs, TSRs, or device drivers. The function returns both the real mode segment base address of the block and one descriptor that can be used by protected mode applications to access the block. This function should only used for temporary buffers to get real mode information (e.g. interrupts that need a data structure in ES:(E)DI), because every single block needs an unique selector. The returned selector should only be freed by a global_dos_free call.

Errors
  Check the `int31error` variable.
See also
  global_dos_free

Example

      uses
      	go32;

      procedure dosalloc(var selector : word;
      	var segment : word; size : longint);
      var
      	res : longint;
      begin
      	res := global_dos_alloc(size);
      	selector := word(res);
      	segment := word(res shr 16);
      end;

      procedure dosfree(selector : word);
      begin
      	global_dos_free(selector);
      end;

      type
      	VBEInfoBuf = packed record
      		Signature : array[0..3] of char;
      		Version : Word;
      		reserved : array[0..505] of byte;
      	end;

      var
      	selector,
      	segment : Word;

      	r : trealregs;
      	infobuf : VBEInfoBuf;

      begin
      	fillchar(r, sizeof(r), 0);
      	fillchar(infobuf, sizeof(VBEInfoBuf), 0);
      	dosalloc(selector, segment, sizeof(VBEInfoBuf));
      	if (int31error<>0) then begin
      		Writeln('Error while allocating real mode memory, halting');
      		halt;
      	end;
      	infobuf.Signature := 'VBE2';
      	dosmemput(segment, 0, infobuf, sizeof(infobuf));
      	r.ax := $4f00; r.es := segment;
      	realintr($10, r);
      	dosmemget(segment, 0, infobuf, sizeof(infobuf));
      	dosfree(selector);
      	if (r.ax <> $4f) then begin
      		Writeln('VBE BIOS extension not available, function call ',
      			'failed');
      		halt;
      	end;
      	if (infobuf.signature[0] = 'V') and
      		(infobuf.signature[1] = 'E') and
      		(infobuf.signature[2] = 'S') and
      		(infobuf.signature[3] = 'A') then begin
      		Writeln('VBE version ', hi(infobuf.version), '.',
      			lo(infobuf.version), ' detected');
      	end;
      end.

##
31 global_dos_free

Declaration
  `Function global_dos_free (selector :Word) : boolean;`

  ``

Description
  Frees a previously allocated DOS memory block. Parameters:
  selector:
    selector to the DOS memory block.
  Return value: `True` if successful, `False` otherwise. Notes: The descriptor allocated for the memory block is automatically freed and hence invalid for further use. This function should only be used for memory allocated by global_dos_alloc.

Errors
  Check the `int31error` variable.
See also
  global_dos_alloc

For an example, see global_dos_alloc.

##
32 inportb

Declaration
  `Function inportb (port : Word) : byte;`

  ``

Description
  Reads 1 byte from the selected I/O port. Parameters:
  port:
    the I/O port number which is read.
  Return values: Current I/O port value.

Errors
  None.
See also
  outportb, inportw, inportl

##
33 inportl

Declaration
  `Function inportl (port : Word) : Longint;`

  ``

Description

  Reads 1 longint from the selected I/O port. Parameters:

  port:
    the I/O port number which is read.
  Return values: Current I/O port value.

Errors
  None.
See also
  outportb, inportb, inportw

##
34 inportw

Declaration
  `Function inportw (port : Word) : Word;`

  ``

Description

  Reads 1 word from the selected I/O port. Parameters:

  port:
    the I/O port number which is read.
  Return values: Current I/O port value.

Errors
  None.
See also
  outportw inportb, inportl

##
35 lock_code

Declaration
  `Function lock_code (functionaddr : pointer; size : Longint) : boolean;`

  ``

Description
  Locks a memory range which is in the code segment selector. Parameters:
  functionaddr:
    address of the function to be locked.
  size:
    size in bytes to be locked.
  Return values: `True` if successful, `False` otherwise.

Errors
  Check the `int31error` variable.
See also

  lock_linear_region, lock_data, unlock_linear_region, unlock_data, unlock_code

For an example, see get_rm_callback.

##
36 lock_data

Declaration
  `Function lock_data (var data; size : Longint) : boolean;`

  ``

Description
  Locks a memory range which resides in the data segment selector. Parameters:
  data:
    address of data to be locked.
  size:
    length of data to be locked.
  Return values: `True` if successful, `False` otherwise.

Errors
  Check the `int31error` variable.
See also

  lock_linear_region, lock_code, unlock_linear_region, unlock_data, unlock_code

For an example, see get_rm_callback.

##
37 lock_linear_region

Declaration
  `Function lock_linear_region (linearaddr, size : Longint) : boolean;`

  ``

Description
  Locks a memory region to prevent swapping of it. Parameters:
  linearaddr:
    the linear address of the memory are to be locked.
  size:
    size in bytes to be locked.
  Return value: `True` if successful, False otherwise.

Errors
  Check the `int31error` variable.
See also

  lock_data, lock_code, unlock_linear_region, unlock_data, unlock_code

##
38 outportb

Declaration
  `Procedure outportb (port : Word; data : byte);`

  ``

Description
  Sends 1 byte of data to the specified I/O port. Parameters:
  port:
    the I/O port number to send data to.
  data:
    value sent to I/O port.
  Return values: None.

Errors
  None.
See also
  inportb, outportl, outportw

Example

      uses
      	crt,
      	go32;

      begin
      	outportb($61, $ff);
      	delay(50);
      	outportb($61, $0);
      end.

##
39 outportl

Declaration
  `Procedure outportl (port : Word; data : Longint);`

  ``

Description
  Sends 1 longint of data to the specified I/O port. Parameters:
  port:
    the I/O port number to send data to.
  data:
    value sent to I/O port.
  Return values: None.

Errors
  None.
See also
  inportl, outportw, outportb

For an example, see outportb.

##
40 outportw

Declaration
  `Procedure outportw (port : Word; data : Word);`

  ``

Description
  Sends 1 word of data to the specified I/O port. Parameters:
  port:
    the I/O port number to send data to.
  data:
    value sent to I/O port.
  Return values: None.

Errors
  None.
See also
  inportw, outportl, outportb

For an example, see outportb.

##
41 realintr

Declaration
  `Function realintr (intnr: Word; var regs : trealregs) : boolean;`

  ``

Description
  Simulates an interrupt in real mode. Parameters:
  intnr:
    interrupt number to issue in real mode.
  regs:
    registers data structure.
  Return values: The supplied registers data structure contains the values that were returned by the real mode interrupt. `True` if successful, `False` if not. Notes: The function transfers control to the address specified by the real mode interrupt vector of intnr. The real mode handler must return by executing an IRET.

Errors
  Check the `int31error` variable.
See also

Example

      uses
      	go32;

      var
      	r : trealregs;

      begin
      	r.ax := $5300;
      	r.bx := 0;
      	realintr($15, r);
      	if ((r.flags and carryflag)=0) then begin
      		Writeln('APM v', (r.ah and $f), '.',
      			(r.al shr 4), (r.al and $f), ' detected');
      	end else
      		Writeln('APM not present');
      end.

##
42 seg_fillchar

Declaration
  `Procedure seg_fillchar (seg : Word; ofs : Longint; count : Longint; c : char);`

  ``

Description

  Sets a memory area to a specific value. Parameters:

  seg:
    selector to memory area.
  ofs:
    offset to memory.
  count:
    number of bytes to set.
  c:
    byte data which is set.
  Return values: None. Notes: No range check is done in any way.

Errors
  None.
See also
  seg_move, seg_fillword, dosmemfillchar, dosmemfillword, dosmemget, dosmemput, dosmemmove

Example

      uses
      	go32;

      var
      	vgasel : Word;
      	r : trealregs;

      begin
      	r.eax := $13; realintr($10, r);
      	vgasel := segment_to_descriptor($A000);
      	seg_fillchar(vgasel, 0, 64000, #15);
      	readln;
      	r.eax := $3; realintr($10, r);
      end.

##
43 seg_fillword

Declaration
  `Procedure seg_fillword (seg : Word; ofs : Longint; count : Longint; w :Word);`

  ``

Description

  Sets a memory area to a specific value. Parameters:

  seg:
    selector to memory area.
  ofs:
    offset to memory.
  count:
    number of words to set.
  w:
    word data which is set.
  Return values: None. Notes: No range check is done in any way.

Errors
  None.
See also

  seg_move, seg_fillchar, dosmemfillchar, dosmemfillword, dosmemget, dosmemput, dosmemmove

For an example, see allocate_ldt_descriptors.

##
44 segment_to_descriptor

Declaration
  `Function segment_to_descriptor (seg : Word) : Word;`

  ``

Description

  Maps a real mode segment (paragraph) address onto an descriptor that can be used by a protected mode program to access the same memory. Parameters:

  seg:
    the real mode segment you want the descriptor to.
  Return values: Descriptor to real mode segment address. Notes: The returned descriptors limit will be set to 64 kB. Multiple calls to this function with the same segment address will return the same selector. Descriptors created by this function can never be modified or freed. Programs which need to examine various real mode addresses using the same selector should use the function allocate_ldt_descriptors and change the base address as necessary.

Errors
  Check the `int31error` variable.
See also
  allocate_ldt_descriptors, free_ldt_descriptor, set_segment_base_address

For an example, see seg_fillchar.

##
45 seg_move

Declaration
  `Procedure seg_move (sseg : Word; source : Longint; dseg : Word; dest : Longint; count : Longint);`

  ``

Description
  Copies data between two memory locations. Parameters:
  sseg:
    source selector.
  source:
    source offset.
  dseg:
    destination selector.
  dest:
    destination offset.
  count:
    size in bytes to copy.
  Return values: None. Notes: Overlapping is only checked if the source selector is equal to the destination selector. No range check is done.

Errors
  None.
See also

  seg_fillchar, seg_fillword, dosmemfillchar, dosmemfillword, dosmemget, dosmemput, dosmemmove

For an example, see allocate_ldt_descriptors.

##
46 set_descriptor_access_rights

Declaration
  `Function set_descriptor_access_rights (d : Word; w : Word) : Longint;`

  ``

Description

  Sets the access rights of a descriptor. Parameters:

  d:
    selector.
  w:
    new descriptor access rights.
  Return values: This function doesn't return anything useful.

Errors
  Check the `int31error` variable.
See also

  get_descriptor_access_rights

##
47 set_pm_interrupt

Declaration
  `Function set_pm_interrupt (vector : byte; const intaddr : tseginfo) : boolean;`

  ``

Description
  Sets the address of the protected mode handler for an interrupt. Parameters:
  vector:
    number of protected mode interrupt to set.
  intaddr:
    selector:offset address to the interrupt vector.
  Return values: `True` if successful, `False` otherwise. Notes: The address supplied must be a valid `selector:offset` protected mode address.

Errors
  Check the `int31error` variable.
See also
  get_pm_interrupt, set_rm_interrupt, get_rm_interrupt

Example

      uses
      	crt,
      	go32;

      const
      	int1c = $1c;

      var
      	oldint1c : tseginfo;
      	newint1c : tseginfo;

      	int1c_counter : Longint;

      	int1c_ds : Word; external name '___v2prt0_ds_alias';

      procedure int1c_handler; assembler;
      asm
         cli
         pushw %ds
         pushw %ax
         movw %cs:int1c_ds, %ax
         movw %ax, %ds
         incl int1c_counter
         popw %ax
         popw %ds
         sti
         iret
      end;

      var i : Longint;

      begin
           newint1c.offset := @int1c_handler;
           newint1c.segment := get_cs;
           get_pm_interrupt(int1c, oldint1c);
           Writeln('-- Press any key to exit --');
           set_pm_interrupt(int1c, newint1c);
           while (not keypressed) do begin
                 gotoxy(1, wherey);
                 write('Number of interrupts occured : ', int1c_counter);
           end;
           set_pm_interrupt(int1c, oldint1c);
      end.

##
48 set_rm_interrupt

Declaration
  `Function set_rm_interrupt (vector : byte; const intaddr : tseginfo) : boolean;`

  ``

Description
  Sets a real mode interrupt handler. Parameters:
  vector:
    the interrupt vector number to set.
  intaddr:
    address of new interrupt vector.
  Return values: `True` if successful, otherwise `False`. Notes: The address supplied MUST be a real mode segment address, not a `selector:offset` address. So the interrupt handler must either reside in DOS memory (below 1 Mb boundary) or the application must allocate a real mode callback address with get_rm_callback.

Errors
  Check the `int31error` variable.
See also

  get_rm_interrupt, set_pm_interrupt, get_pm_interrupt, get_rm_callback

##
49 set_segment_base_address

Declaration
  `Function set_segment_base_address (d : Word; s : Longint) : boolean;`

  ``

Description
  Sets the 32-bit linear base address of a descriptor. Parameters:
  d:
    selector.
  s:
    new base address of the descriptor.

Errors
  Check the `int31error` variable.
See also

  allocate_ldt_descriptors, get_segment_base_address, allocate_ldt_descriptors, set_segment_limit, get_segment_base_address, get_segment_limit

##
50 set_segment_limit

Declaration
  `Function set_segment_limit (d : Word; s : Longint) : boolean;`

  ``

Description
  Sets the limit of a descriptor. Parameters:
  d:
    selector.
  s:
    new limit of the descriptor.
  Return values: Returns `True` if successful, else `False`. Notes: The new limit specified must be the byte length of the segment - 1. Segment limits bigger than or equal to 1MB must be page aligned, they must have the lower 12 bits set.

Errors
  Check the `int31error` variable.
See also
  allocate_ldt_descriptors, set_segment_base_address, get_segment_limit, set_segment_limit

For an example, see allocate_ldt_descriptors.

##
51 tb_size

Declaration
  `Function tb_size : Longint;`

  ``

Description
  Returns the size of the pre-allocated DOS memory buffer. Parameters: None. Return values: The size of the pre-allocated DOS memory buffer. Notes: This block always seems to be 16k in size, but don't rely on this.

Errors
  None.
See also
  transfer_buffer, copyfromdos copytodos

##
52 transfer_buffer

Declaration
  `Function transfer_buffer : Longint;`
Description
  transfer_buffer returns the offset of the transfer buffer.
Errors
  None.
See also
  tb_size

##
53 unlock_code

Declaration
  `Function unlock_code (functionaddr : pointer; size : Longint) : boolean;`

  ``

Description
  Unlocks a memory range which resides in the code segment selector. Parameters:
  functionaddr:
    address of function to be unlocked.
  size:
    size bytes to be unlocked.
  Return value: `True` if successful, `False` otherwise.

Errors
  Check the `int31error` variable.
See also
  unlock_linear_region, unlock_data, lock_linear_region, lock_data, lock_code

For an example, see get_rm_callback.

##
54 unlock_data

Declaration
  `Function unlock_data (var data; size : Longint) : boolean;`

  ``

Description
  Unlocks a memory range which resides in the data segment selector. Paramters:
  data:
    address of memory to be unlocked.
  size:
    size bytes to be unlocked.
  Return values: `True` if successful, `False` otherwise.

Errors
  Check the `int31error` variable.
See also
  unlock_linear_region, unlock_code, lock_linear_region, lock_data, lock_code

For an example, see get_rm_callback.

##
55 unlock_linear_region

Declaration
  `Function unlock_linear_region (linearaddr, size : Longint) : boolean;`

  ``

Description
  Unlocks a previously locked linear region range to allow it to be swapped out again if needed. Parameters:
  linearaddr:
    linear address of the memory to be unlocked.
  size:
    size bytes to be unlocked.
  Return values: `True` if successful, `False` otherwise.

Errors
  Check the `int31error` variable.
See also

  unlock_data, unlock_code, lock_linear_region, lock_data, lock_code