5.12 Memory management

• Maccess	Verify accessibility of a region of memory.
• Maddalt	Registers 'Alternative' memory.
• Malloc	Reserves memory or inquires free memory.
• Mfree	Releases a block of memory.
• Mshrink	Reduces/increases size of a memory block.
• Mvalidate	Verify accessibility of a process region of memory.
• Mxalloc	Reserves a block of memory.

Warning: Here one should emphasise that in view of future operating system versions, memory blocks used for communication between different programs, or blocks allocated via pointers, have to be global (Mxalloc functions with a global flag). Otherwise, when using computers with PMMU (e.g. Atari-TT030 or Falcon030), memory protection violations may arise.

See also:
Program launch and TPA Process functions Memory management in TOS Memory management in MagiC

5.12.1 Maccess

Name:

Maccess - verify accessibility of a region of memory

Opcode:

381 (0x17d)

Syntax:

int32_t Maccess ( void *start, int32_t size, int16_t mode );

Description:

Maccess verifies accessibility for the calling process's memory page(s) containing any part of the address range in the interval [addr, addr+len-1].

Parameter	Meaning
start	Start address of the memory block to be verified list
size	Length of the memory block
mode	mode is either 1 to check for read access, or 0 to check for read/write access.

Return value:

The function returns the value 0 on success, else a negative error code.

Availability:

This function is available as of FreeMiNT 1.15.12.

Group:

Memory management

See also:

Binding Mfree Malloc Mxalloc Mvalidate

5.12.1.1 Bindings for Maccess

C:	int32_t Maccess ( void *start, int32_t size, int16_t mode );
Assembler:	move.w mode,-(sp) ; Offset 10 move.l size,-(sp) ; Offset 6 pea start ; Offset 2 move.w #381,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $C(sp),sp ; Correct stack

5.12.2 Maddalt

Name:

»Inform GEMDOS of alternative memory« - Register 'Alternative' RAM with GEMDOS.

Opcode:

Syntax:

int32_t Maddalt ( void *start, int32_t size );

Description:

The GEMDOS routine Maddalt permits the inclusion of a block of additional alternate-RAM in the GEMDOS memory list that would not normally have been identified by the system. The following apply:

Parameter	Meaning

start	Start address of the memory block to be added to the GEMDOS free list
size	Length of the memory block

Note: The block remains the property of DOS and may not be reclaimed. If the added blocks are not consecutive, the number of blocks that can be added is restricted to around 12.

This function could be useful perhaps when using VME-bus cards in an Atari-TT030, or similar hardware modifications, if their memory is to be made accessible to GEMDOS.

Return value:

The function returns the value 0 on success, else a negative error code.

Availability:

The function is only available from GEMDOS 0.19 on.

Group:

Memory management

See also:

Binding Mfree Malloc Mxalloc

5.12.2.1 Bindings for Maddalt

C:	int32_t Maddalt ( void *start, int32_t size );
Assembler:	move.l size,-(sp) ; Offset 6 pea start ; Offset 2 move.w #20,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $A(sp),sp ; Correct stack

5.12.3 Malloc

Name:

»memory allocation« - Reserve a block of memory or inquire free memory.

Opcode:

Syntax:

void *Malloc ( int32_t number );

Description:

The GEMDOS routine Malloc reserves a block of memory for an application, or calculates the size of the largest free block of memory. The following applies for the parameter number:

Value	Meaning

-1	Get size of the largest available memory block
Other	Number of bytes to be reserved

Note: One should never rely on the number of bytes actually allocated corresponding to the number requested. Constructs of the type Malloc(Malloc(-1L)) are simply out of the question in multitasking systems (catchword: Task-switching).

Under TOS the GEMDOS supported only a limited number of memory blocks. For that reason, a programm should not often use the function, instead it reserve larger blocks (at least 16KBytes) and manage themselves.

Furthermore one should note the following poins:

The memory block need not be empty.
Memory blocks allocated consecutively need not necessarily be contiguous.
Never access memory blocks that do not belong to one's own process. In systems with memory protection this would lead to an exception.

In MagiC this call is implemented as Mxalloc with mode 0 or 3 (depending on the configuration bits in the program file header). The configuration bits are stored in the basepage at present.

Return value:

The function returns the start address of the reserved memory block. A NULL-pointer means that there is not enough memory available to fulfill the request. In the case of number = -1, the length of the largest available memory block will be returned.

Availability:

All GEMDOS versions. However, prior to GEMDOS Version 0.15, Malloc( 0L ) will return a pointer to invalid memory instead of failing as it should.

Group:

Memory management

See also:

Bindings for Malloc Mfree Mxalloc Maddalt Program flags

5.12.3.1 Bindings for Malloc

C:	void *Malloc ( int32_t number );
Assembler:	move.l number,-(sp) ; Offset 2 move.w #72,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #6,sp ; Correct stack

5.12.4 Mfree

Name:

»memory free« - Release a block of memory.

Opcode:

Syntax:

int32_t Mfree ( void *block );

Description:

The GEMDOS routine Mfree releases a block of memory previously reserved with Malloc.

The parameter block contains the start address of the memory block to be released.

Note: In almost all GEMDOS versions no check is made whether the block to be released really belongs to the relevant process. Hence particular care is needed, specially in multitasking systems.

Return value:

The function can return the following results:

E_OK	No error has arisen
EIMBA	Invalid memory block address

Availability:

All GEMDOS versions.

Group:

Memory management

See also:

Binding Malloc Mxalloc Maddalt

5.12.4.1 Bindings for Mfree

C:	int32_t Mfree ( void *block );
Assembler:	pea block ; Offset 2 move.w #73,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #6,sp ; Correct stack

5.12.5 Mshrink

Name:

»Memory shrink« - Reduce or enlarge a memory block.

Opcode:

Syntax:

int32_t Mshrink ( void *block, int32_t newsiz );

Description:

The GEMDOS routine Mshrink reduces or enlarges an already reserved memory block in the GEMDOS free list. The following apply:

Parameter

Meaning

block

Start address of the memory block

newsiz

New (changed) length of the block; in MagiC additionally:

-1 =	Obtain the largest possible size of the memory block
0 =	Release block

Note: As a rule no check is made whether the memory block really belongs to the caller. The option to enlarge a memory block is only available in MagiC at present. However this only works if a large enough free block is present above the block in question, and the TOS-compatibility has been deactivated.

Return value:

The function can return the following results:

E_OK :	No error has arisen
EIMBA :	Invalid memory block address
EGSBF :	Block was enlarged

Availability:

All GEMDOS versions.

Group:

Memory management

See also:

Binding Malloc Mfree

5.12.5.1 Bindings for Mshrink

C:	int32_t Mshrink ( void *block, int32_t newsiz );
Assembler:	move.l newsiz,-(sp) ; Offset 8 pea block ; Offset 4 move.w #0,-(sp) ; Offset 2 move.w #74,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $C(sp),sp ; Correct stack Note: The NULL-parameter is normally added automatically in a C binding.

5.12.6 Mvalidate

Name:

Mvalidate - verify access to a process memory region

Opcode:

321 (0x141)

Syntax:

int32_t Mvalidate ( int16_t pid, void *start, int32_t size, int32_t *flags );

Description:

Mvalidate verifies accessibility for the specified process's memory page(s) containing any part of the address range in the interval [addr, addr+len-1].

Parameter	Meaning
pid	Process id of the process to check. May be 0 for the current process.
start	Start address of the memory block to be verified.
size	Length of the memory block.
flags	Upon a successfull call, will contain the protection flags of the specified memory region.

Return value:

The function returns the value 0 on success, else a negative error code.

Availability:

This function is available as of FreeMiNT 1.15.12.

Group:

Memory management

See also:

Binding Mfree Malloc Mxalloc Maccess

5.12.6.1 Bindings for Mvalidate

C:	int32_t Mvalidate ( int16_t pid, void start, int32_t size, int32_t flags );
Assembler:	pea flags ; Offset 12 move.l size,-(sp) ; Offset 8 pea start ; Offset 4 move.w pid,-(sp) ; Offset 2 move.w #321,-(sp) ; Offset 0 trap #1 ; GEMDOS lea $10(sp),sp ; Correct stack

5.12.7 Mxalloc

Name:

»Allocate memory (with preference)« - Reserve memory according to specified preferences.

Opcode:

Syntax:

void *Mxalloc ( int32_t amount, int16_t mode );

Description:

The GEMDOS routine Mxalloc reserves a block of memory of the size amount. One can use the bits of the WORD parameter mode to specify the desired type of memory. The following apply:

Bits

Meaning

0-2

Treatment of the TT-RAM

0 =	Allocate ST-RAM only
1 =	Allocate Alternative-RAM only
2 =	Allocate either, ST-RAM preferred
3 =	Allocate either, Alternative-RAM preferred

Reserved

4-7

Protection mode

0 =	Default (from your PRGFLAGS)
1 =	Private
2 =	Global
3 =	Supervisor-mode-only access
4 =	World-readable access

Other values are undefined and reserved.

No-Free modus
When set, this bit means "if the owner of this block terminates, don't free this block. Instead, let MiNT inherit it, so it'll never be freed." This is a special mode meant for the OS only, and may not remain available to user processes.

All further bits are reserved for future purposes. With the value -1L for amount one can inquire the size of the largest contiguous block of memory (dependent on mode).

Under MagiC all memory allocations are logged. If the restriction set with LIMITMEM is exceeded, A NULL-pointer will be returned. In the case amount = -1, the minimum of free memory and not yet exhausted LIMITMEM restriction will be returned. Exceptions are calls of the screen manager (SCRENMGR) which controls the menus. This ensures that even LIMITMEM-restricted programs do not have problems with menu redraws.

Note: A problem exists in ascertaining when the extended modes (bits 3 and following) may be used. This is because some older versions of GEMDOS do not get along with these modes and are partly responsible for crashing the application or the whole system. For this reason many programmers test explicitly for the presence of MiNT/MultiTOS or versions of MagiC >= 2.0. Alternatively one can also use the function Mxmask.

Return value:

The function returns the start address of the reserved block as an untyped pointer. Mxalloc returns a 0 when insufficient memory is available.

Availability:

This function exists only from GEMDOS Version 0.19 on.

Group:

Memory management

See also:

Binding Mfree Malloc Maddalt Program flags

5.12.7.1 Bindings for Mxalloc

C:	void *Mxalloc ( int32_t amount, int16_t mode );
Assembler:	move.w mode,-(sp) ; Offset 6 move.l amount,-(sp) ; Offset 2 move.w #68,-(sp) ; Offset 0 trap #1 ; GEMDOS addq.l #8,sp ; Correct stack

5.12.7.2 Mxmask

/*
   Mxmask returns a bit-mask with which one should mask the mode
   WORD of a Mxalloc call if one wants to use protection bits.
   This is necessary as Mxalloc unfortunately returns erroneous
   results in some GEMDOS implementations when protection bits are
   specified, which can result in a system crash.
   (© 1994 Martin Osieka)

   Application example:
   mxMask = Mxmask();
   p = mxMask ? Mxalloc( size, 0x43 & mxMask) : Malloc( size); */

SHORT Mxmask (void)
{
    void *svStack;         /* Supervisor-Stack */
    int32_t sRAM, sRAMg;   /* ST-RAM           */
    int32_t aRAM, aRAMg;   /* Alternate RAM    */

    /*
    // Sample table of possible values:
    //           | newfashion  | oldfashion
    // sRAM aRAM | sRAMg aRAMg | sRAMg aRAMg
    //   1    0  |   1     0   |   1     1
    //   0    2  |   0     2   |   2     2
    //   1    2  |   1     2   |   3     3
    */

    svStack = (void *) Super( 0);  /* Disallow task-switching */

    sRAM  = (int32_t) Mxalloc( -1, 0);
    /* In error case Mxalloc( -1, 3) */
    sRAMg = (int32_t) Mxalloc( -1, 0x40);
    aRAM  = (int32_t) Mxalloc( -1, 1);
    /* In error case Mxalloc( -1, 3) */
    aRAMg = (int32_t) Mxalloc( -1, 0x41);

    Super( svStack);  /* Permit task-switching */

    if (sRAM == -32)
        return 0x0000;  /* Mxalloc is not implemented */

    else if ( ((sRAM + aRAM) == sRAMg) && ((sRAM + aRAM) == aRAMg) )
        return 0x0003;  /* oldfashion Mxalloc() */

    else
        return 0xFFFF;

} /* Mxmask */