AmigaOS Documentation Wiki - User contributions [en]

Exec Memory Allocation

2024-12-08T02:54:28Z

Ryan Dixon: /* Program Address Space */

== Exec Memory Allocation ==

Exec manages all of the free memory currently available in the system. Using a slab allocation system, Exec keeps track of memory and provides the functions to allocate and access it.

When an application needs some memory, it can either declare the memory statically within the program or it can ask Exec for some memory. When Exec receives a request for memory, it searches its free memory regions to find a suitably sized block that matches the size and attributes requested.

Prior to AmigaOS 4.0, the OS did not make use of the CPU's memory management unit and used memory "as-is". That is, if you have different memory expansions plugged into your system, the memory will be seen as chunks located somewhere in the 4 gigabyte address space. Since version 4.0, the MMU will be used to "map" memory pages from their physical location to a virtual address. There are multiple reasons why this is better than using the verbatim physical addresses - among other things it reduces the effect of "memory fragmentation" and simplifies the possibility to swap currently unused memory pages to persistent storage such as a hard disk.

The "downside" is that the virtual address of a memory block is almost never identical to the physical address. This isn't much of a downside, since an application will never really need to care about it. If an application allocates a block of memory of n bytes, it will get a pointer back that points to at least n continuous addresses as expected. The pages that "fill" this memory block may come from different physical locations scattered throughout the physical memory but a program will never noticed that. For all intent and purpose, the application sees a single continuous block of memory.

=== Program Address Space ===

It is important to remember that, just like in classic AmigaOS, a single address space is used for all programs. Sometimes the mention of an MMU can lead people to assume that each process on the Amiga will have its own personal, partitioned address space. The following two programs demonstrate that, even though they are separate processes, it is possible to read and write another's memory. The memory locations are the same virtual address and that virtual address maps onto the same physical address.

This program has a global variable. It prints out the virtual address of the global, the value at that address (which can be optionally specified), waits for a keypress and, finally, prints out the value at that same address again in case it has been externally updated (which is done by the subsequent program listing):
<pre>
#include <stdlib.h>
#include <stdio.h>

volatile char x = 127;

/* Usage: a [VAL] */
int main(int argc, char *argv[])
{
if(argc==2)
x = (char)atoi(argv[1]);

printf("Virtual Address of `x': %p\n", (void*)&x);
printf("Dereferenced Value of `x': %d\n", x);
(void)getchar();
printf("Final Value of `x': %d\n", x);
return 0;
}
</pre>

This program reads in an address as an argument and prints the value at that address even though it does not "own" the memory. By adding an additional argument, this program can also write to that "foreign" address. After this program is complete, you can press a key on the previous program and see that the value changed:
<pre>
#include <stdlib.h>
#include <stdio.h>

/* Usage: b ADDR [VAL_TO_WRITE] */
int main(int argc, char *argv[])
{
if(!(argc==2 || argc==3))
return 10;

volatile char *byte = (volatile char*)strtol(argv[1],NULL,16);
printf("Selected Virtual Address : %p\n",(void*)byte);
printf("Dereferenced Value of Address: %d\n",*byte);
if(argc==3)
{
printf("Writing Value `%d' to Address: %p\n",atoi(argv[2]),(void*)byte);
*byte=(char)atoi(argv[2]);
}

return 0;
}
</pre>

The same applies for stack and heap allocated memory.

=== Slab allocation ===

[[File:SlabDiagram.jpg|right]]

The AmigaOS memory architecture is based on the "slab allocator" system or "object cache". In essence, the slab allocator only allocates objects of a single size, allocating these in larger batches ("slabs") from the low-level page allocator. These slabs are then divided up into buffers of the required size, and kept within a list in the slab allocator.

Allocating an object with the slab allocator becomes a process of simple node removal: the first node in the first slab containing free nodes is removed and returned for use. Since the slab allocator keeps free slabs or partially free slabs in a separate list from the full slabs, this operation can be carried out in constant time. Freeing memory is accomplished by returning the buffer to its cache, and adding it to its original slab's free list. Slabs that are completely free can be returned to the system's page pool (this operation is actually driven by demand, and timestamps are used to avoid unnecessary loading of data, or "thrashing"). External fragmentation is minimal, and internal fragmentation is controlled and guaranteed not to exceed a certain amount.

=== Object caching ===

The slab allocator can also be used to cache objects. In the real world a lot of memory allocation operations will be used to allocate the same object. The system has a number of data structures which are allocated frequently (semaphores, message ports and the like). Every time such structures are allocated, they must be initialised, and when they are deleted again, they must be cleaned up. It's likely, however, that such a structure will be needed again in the future, so that it can be kept in its initialised state and re-used later. This further reduces the load on the allocator routines, and thus improves system performance.

The object caches work on memory that has already been mapped into the virtual memory space.

=== More Advantages ===

Another advantage is the possibility to improve CPU cache usage. Usually, most objects have "hot spots", i.e. they have a few fields that are used often. Since most of the time a little memory is left unused in a slab (the object size might not be a multiple of the slab size), this additional memory can be used to "shift" the hot spots by a few bytes to optimise the memory structure, leading to better cache usage.

Finally, the system can be expanded to multiple CPUs with next to no overhead. On multi-CPU system, these expanded slab allocators scale almost linearly with the number of CPUs employed, making it the ideal choice for such systems.

The combination of object caching and keeping caches for different memory blocks (for AllocVec/FreeVec emulation) makes the memory management more efficient, faster, and generally more future-proof than the old free list approach used in AmigaOS 3.x and earlier.

See Wikipedia for more information on [http://en.wikipedia.org/wiki/Slab_allocation slab allocator systems].

=== Physical page allocation ===

Every memory location in a computer system has its own, unique address. That is, there is a byte location at address x where you can store and retrieve a single byte. This address is fixed; there is no way to change it without physically changing the hardware. Therefore, this address is called the “physical” address.

The physical address of a memory page is most often completely irrelevant to the application. The CPU will typically only see the virtual address. AmigaOS will take care of assigning virtual addresses to memory paging. This is often called “mapping” a page. Only in very special cases will the physical address be relevant. For example, device drivers that want to pass memory to a hardware device via DMA. Since the MMU is part of the CPU, any external hardware like an IDE controller will not see the virtual but only physical addresses.

A common operation in memory allocation is the assignment of virtual addresses to physical memory locations. Allocation of physical memory is usually done differently from virtual allocations, since it's necessary to free up only part of the allocation (when for example the pager kicks in).

The de-facto standard in allocation of physical pages is a method invented by Knuth, called [http://en.wikipedia.org/wiki/Buddy_memory_allocation the "buddy system"]. Basically every modern operating system uses it and AmigaOS is no exception.

Buddy systems are in essence size-segregated free lists. To allocate, the system searches for a free block of at least the size of the allocation. Then, if the block is too large, it's split into two even-sized blocks. These blocks are called "buddies". One block is returned to it's appropriate free list, and the other is considered further, maybe splitting it further until it's size matches that of the allocation.

In a buddy system, it's easy to determine whether the "buddy" is free or not, because it's address can simply be decided based on the address of the block to be freed.

=== Virtual address space allocation ===

Most CPUs come with a special unit that is called a "memory management unit" or "MMU" for short. The MMU's primary job is to rearrange the physical memory within the 4 gigabytes of address space in a way that is convenient for the operating system and/or applications. To do that effectively, it divides the memory into blocks (called "pages"). For every page the MMU has an entry in a table that specifies where the CPU should "see" this page, and what special attributes the page has. The address where the CPU "sees" this page is a 32 bit address as well, but since the memory is not really located there, we call that a "virtual" address.

AmigaOS uses a resource map allocator for allocating virtual address space. Basically this is a means of managing a set of resources (not necessarily memory). For performance reason, it uses several optimization techniques.

For one, all free resource blocks are held in space-segregated lists, i.e. there is a list for each power-of-two resource group. This makes allocations a lot faster by providing an upper and lower bound for a search. For example, if you want to allocate a block of 2^10 bytes, you can basically skip searching any block below 2^10 bytes in size simply because it won't fit. Similarly, you don't need to search for blocks that are larger than, say, twice the size of the block, since there might still be blocks of a size near to what we need. Size-segregated free lists help narrow down the search, making the search itself faster and the result better in terms of fragmentation.

In addition, the resource maps use object caches for accelerating "small" allocations. Most allocations are below a certain size. For example, the virtual addresses are always allocated in chunks of at least one "page" in memory (4096 bytes). So it's common to allocate blocks of one, two, four, or eight pages. The object caches provide an easy method for keeping these common sizes, making every allocation of these sizes an exact fit, further reducing fragmentation.

=== Page cache ===

A lot of the time spent in allocating memory was spent looking for the appropriate pages in memory. A 256 MB memory system has 65536 4KB pages. These pages have to be searched for from time to time. Originally, hash tables were used but it turned out that distributing 65536 page entries over a few hash buckets still produced lists of several thousand pages that had to be traversed to find a page. The hash table was replaced with a radix tree. These trees are rather broad, but shallow, making traversal very fast. In usual circumstances, the tree does not grow more than 4 to 5 levels in depth, making searching of a page a matter of maximum 4 to 5 compare operations.

=== Pager ===

AmigaOS has the possibility to swap out parts of memory to disk in order to free up more memory for other applications. This feature allows applications to use more memory than is actually physically installed in the system.

Paging is commonly referred to as "virtual memory" by users and sometimes even software developers. The fact AmigaOS uses virtual memory does not imply the use of the pager.

The system can be tuned to different strategies, either page out only on demand (for highly interactive tasks), or based on other needs (lots of free memory in core for disk caches etc.).

The optimized data structures allow the memory system to operate at a very high speed.

The time for a memory allocation is now in the order of a few microseconds. This is especially true for small allocation (below 8096 bytes). During system testing it was observed that by the time the system has booted up to Workbench, there have already been 40,000 allocations to the global memory pool below 2096 bytes.

== Memory Functions ==

Normally, an application uses the AllocVecTags() function to ask for memory:

<syntaxhighlight>
void *AllocVecTags(uint32 size, uint32 tag1, ...);
</syntaxhighlight>

The size argument is the amount of memory the application needs and the tag list specifies the type of memory and any special memory characteristics (described later). If AllocVecTags() is successful, it returns a pointer to a block of memory. The memory allocation will fail if the system cannot find a big enough block with the requested attributes. If AllocVecTags() fails, it returns NULL.

Because the system only keeps track of how much free memory is available and not how much is in use, it has no idea what memory has been allocated by any task. This means an application has to explicitly return, or deallocate, any memory it has allocated so the system can reuse it. If an application does not return a block of memory to the system, the system will not be able to reallocate that memory to some other task. That block of memory will be lost until the Amiga is reset. If you are using AllocVecTags() to allocate memory, a call to FreeVec() will return that memory to the system:

<syntaxhighlight>
void FreeVec(void *memoryBlock);
</syntaxhighlight>

Here memoryBlock is a pointer to the memory block the application is returning to the system. The size of the memory block is tracked internally by the system.

Unlike some compiler memory allocation functions, the Amiga system memory allocation functions return memory blocks that are at least longword aligned. This means that the allocated memory will always start on an address which is at least evenly divisible by four. This alignment makes the memory suitable for any system structures or buffers which require word or long word alignment, and also provides optimal alignment for stacks and memory copying.

=== Memory Types ===

There are three primary types of memory in AmigaOS which are summarized in the following table:

{| class="wikitable"
! Type
! Use
|-
| MEMF_PRIVATE
| This memory is private and only accessible within the context of the Task which allocated it. Private memory should always be preferred. Private memory is also swappable by default (i.e. not locked). This memory will not be visible to any other address space.
In a future version of AmigaOS, it is planned to have Task specific address spaces. This means each task could potentially address up to 4 GB of private memory each.
|-
| MEMF_SHARED
| The memory is shared and accessible by any Task in the system without restriction. This memory can be shared between all address spaces and will always appear at the same address in any address space. Shared memory is locked by default and thus is not swappable.
|-
| MEMF_EXECUTABLE
| The memory is used to store executable PowerPC code. This is used two-fold in AmigaOS. First, it allows the system to determine if a function pointer points to real native PowerPC code as opposed to 68k code which needs to be emulated. Second, it prevents common exploits that use stack overflows to execute malicious code. Executable memory is locked by default and thus is not swappable.
|}

=== Memory Attributes ===

Memory allocation on AmigaOS has traditionally been rather complicated. Over time, as new hardware models were released, more memory attribute flags were introduced.

All the various memory allocation functions and strategies have been consolidated and distilled into a single AllocVecTags() function call. Programmers are strongly encouraged to stop using any other function to allocate system memory. Using AllocVecTags() is the only way to guarantee future compatibility with more advanced AmigaOS features yet to come.

If an application does not specify any attributes when allocating memory, the system tries to satisfy the request with the fastest memory available on the system memory lists.

{{Note|title=Make Sure You Have Memory|text=Always check the result of any memory allocation to be sure the type and amount of memory requested is available. Failure to do so will lead to trying to use an non-valid pointer.}}

==== Using Tags ====

The AllocVecTags() function uses a tag list to define what attributes a block of memory must have. The currently supported tags are listed below.

{| class="wikitable"
! Tag (Default)
! Description
|-
| rowspan="4" | AVT_Type
(MEMF_PRIVATE)
|-
| MEMF_PRIVATE: Allocate from the task private heap. This memory will not be visible to any other address space.
|-
| MEMF_SHARED: Allocate from the system shared heap. This memory can be shared between all address spaces and will always appear at the same address in any address space. This memory is locked by default (see AVT_Lock tag below).
|-
| MEMF_EXECUTABLE: Allocate memory that is marked executable. This memory is locked by default (see AVT_Lock tag below).
|-
| AVT_Contiguous
(FALSE)
| Memory allocated with this property is allocated from a contiguous block of physical memory. This makes the memory suitable for DMA purposes when the DMA device does not support scatter/gather operation. For devices that do support scatter/gather use StartDMA() instead.
''Note:'' Physical pages can move at any time, be removed from memory due to paging or otherwise made unavailable unless the memory pages are locked (see LockMemory() function or AVT_Lock tag).
|-
| AVT_Lock
(TRUE or FALSE)
| After allocating memory, lock the associated pages in memory. This will prevent the pages from being moved, swapped out or otherwise being made unavailable. This is useful in conjunction with the AVT_Contiguous tag since it will ensure that the memory will stay contiguous after allocation.
This tag defaults to FALSE for MEMF_PRIVATE allocations and to TRUE for MEMF_SHARED or MEMF_EXECUTABLE.
|-
| AVT_Alignment
(16)
| Define an alignment constraint for the allocated memory block. The returned memory block will be aligned to the given size (in bytes). It's virtual address will be at least a multiple of the AVT_Alignment value.
''Note:'' Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_PhysicalAlignment
(16)
| Define an alignment constraint for the allocated memory block physical address. See AVT_Alignment for more information.
''Note:'' This functionality is mainly used for DMA drivers that require a specific alignment. Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_ClearWithValue
| Clear the newly allocated memory with the given byte value. If this tag is not given the memory block is not cleared.
|-
| AVT_Wait
(TRUE)
| Wait for the memory subsystem to be available. If TRUE, the calling task will be retired until the memory subsystem is available. This might cause a Forbid() to break. When FALSE and the memory subsystem is not currently available, the function will return immediately and the allocation will fail.
|-
| AVT_NoExpunge
(FALSE)
| If allocation fails because of unavailability, prevent invocation of low memory cleanup handlers. The default is FALSE which means that when memory is not available, cleanup handlers are invoked to try and satisfy the allocation.
|}

==== Using Flags ====

The use of memory flags was the only supported way to allocate memory prior to AmigaOS 4.0. It may be still useful to know more about this obsolete system for porting older applications. For more information about the memory flags system see [[Obsolete Exec Memory Allocation]].

=== Allocating System Memory ===

The following examples show how to allocate memory.

<syntaxhighlight>
APTR apointer = IExec->AllocVecTags(100, TAG_END);

if (apointer == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

AllocVecTags() returns the address of the first byte of a memory block that is at least 100 bytes in size or NULL if there is not that much free memory. Because there are no tags specified, private memory is assumed so this memory cannot be shared with any other tasks.

In addition to allocating a block of memory, this function keeps track of the size of the memory block, so your application doesn't have to remember it when it deallocates that memory block. The AllocVecTags() function allocates a little more memory to store the size of the memory allocation request.

{{Note|title=Make No Assumptions|It is not legal to peek the longword in front of the returned memory pointer to find out how big the block is. This has always been illegal regardless of what any other documentation may have stated to the contrary. Your application has access to the memory returned by AllocVecTags() and the only guarantee made is that the returned block has n bytes of continuous address space starting at the returned address. Anything outside this area is not to be touched.}}

<syntaxhighlight>
APTR anotherptr = IExec->AllocVecTags(1000,
AVT_Type, MEMF_SHARED,
AVT_Lock, FALSE,
AVT_ClearWithValue, 0,
TAG_END);

if (anotherptr == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocates shared memory which is accessible by any task in the system and clears the memory contents to zero. MEMF_SHARED memory is locked by default for compatibility with the obsolete MEMF_PUBLIC flag. This is by far the most common case when allocating shared memory.

<syntaxhighlight>
APTR lockedmem = IExec->AllocVecTags(3000,
AVT_Type, MEMF_SHARED,
TAG_END);

if (lockedmem == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocated shared memory which is accessible by any task in the system. MEMF_SHARED memory is locked by default so the underlying memory pages are not moveable and cannot be swapped out. Such memory could be used to share memory between a Process and an interrupt routine for example.

If the system free memory list does not contain enough contiguous memory bytes in an area matching your requirements, AllocVecTags() returns a zero. You ''must'' check for this condition.

<syntaxhighlight>
APTR yap = IExec->AllocVec(500, MEMF_CHIP);

if (yap == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The deprecated AllocVec() function is used in the example above because it is the only way to allocate MEMF_CHIP memory on a classic Amiga system.

=== Locking System Memory ===

The LockMem() function is used to explicitly lock a memory block. This function will make sure your memory block is not unmapped, swapped out or somehow made inaccessible. Use this function wisely. If there is no good reason to lock memory then do not do it. It will prevent the memory system from optimizing memory layout and may lead to poor performance.

<syntaxhighlight>
IExec->LockMem(mem, 1000);
</syntaxhighlight>

Before deallocating the memory is must be unlocked as well.

<syntaxhighlight>
IExec->UnLockMem(mem, 1000);
</syntaxhighlight>

{{Note|title=''Do not forget to UnlockMem()''|Failure to unlock memory will have adverse affects on the memory system. Locked memory pages cannot be moved so the system cannot optimize the layout of locked memory pages.}}

Be careful to always match the number of locks and the number of unlocks. If something else may have locked memory in the same page and an extraneous UnlockMem() decreases the lock reference counter to 0, that page can be paged out or moved. If that happens, for example, with data used in an interrupt handler or by the device driver which handles the swap partition the system will crash.

=== Freeing System Memory ===

The following examples free the memory chunks shown in the previous calls to AllocVecTags().

<syntaxhighlight>
IExec->FreeVec(apointer);

IExec->FreeVec(anotherptr);

IExec->FreeVec(lockedmem);

IExec->FreeVec(yap);
</syntaxhighlight>

A memory block allocated with AllocVecTags() or AllocVec() must be returned to the system pool with the FreeVec() function. This function uses the stored size in the allocation to free the memory block, so there is no need to specify the size of the memory block to free.

Any memory that is locked must be explicitly unlocked with UnlockMem() prior to freeing it. Failure to unlock memory will not cause any immediate problems but any pages which are locked cannot be moved or swapped out which can decrease system performance.

FreeVec() returns no status. However, if you attempt to free a memory block in the middle of a chunk that the system believes is already free, you will cause a system crash. It is also illegal to free the same memory block twice and this will lead to a system crash.

{{Note|title=''Leave Memory Allocations Out Of Interrupt Code''|text=Do not allocate or deallocate system memory from within interrupt code. The [[Exec_Interrupts|Exec Interrupts]] section explains that an interrupt may occur at any time, even during a memory allocation process. As a result, system data structures may not be internally consistent at this time.}}

=== Memory may be Locked by Default ===

By default, the system memory allocation routines will allocate MEMF_SHARED and MEMF_EXECUTABLE memory and implicitly lock it. This memory must not be explicitly unlocked. Let the system handle the unlocking internally.

Here is the right way to allocate and free MEMF_SHARED memory:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->FreeVec(ptr);
</syntaxhighlight>

Here is the wrong way:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->UnlockMem(ptr, 10); // Doing this could lead to undefined system behaviour.
IExec->FreeVec(ptr);
</syntaxhighlight>

Unlocking memory not explicitly locked does not immediately cause any issues. However, in a future version of AmigaOS the memory pages may be handled differently than they are handled today. This could lead to incompatibilities with your applications and AmigaOS. The simple rule is that if you called LockMem() you must also call UnlockMem(). All other times you should not call UnlockMem().

{{Note|Memory locking is done at the page level. Even if a single byte of memory is locked in a page that entire page is locked. The programmer has no control over which pages may be used to satisfy a memory allocation.}}

{{Note|Shared and executable memory is locked implicitly for 68K backwards compatibility reasons. Use AVT_Lock (or equivalent) to ensure your shared and executable memory is not locked. MEMF_PRIVATE memory has no backwards compatibility issues and is always unlocked by default.}}

=== Memory Information Functions ===

The memory information routines AvailMem() and TypeOfMem() can provide the amount of memory available in the system, and the attributes of a particular block of memory.

==== Memory Requirements ====

The same attribute flags used in memory allocation routines are valid for the memory information routines. There is also an additional flag, MEMF_LARGEST, which can be used in the AvailMem() routine to find out what the largest available memory block of a particular type is. Specifying the MEMF_TOTAL flag will return the total amount of memory currently available.

==== Calling Memory Information Functions ====

The following example shows how to find out how much memory of a particular type is available.

<syntaxhighlight>
uint32 size = IExec->AvailMem(MEMF_CHIP | MEMF_LARGEST);
</syntaxhighlight>

AvailMem() returns the size of the largest chunk of available chip memory.

{{Note|title=''AvailMem() May Not Be Totally Accurate''|text=Because of multitasking, the return value from AvailMem() may be inaccurate by the time you receive it.}}

The following example shows how to determine the type of memory of a specified memory address.

<syntaxhighlight>
uint32 memtype = IExec->TypeOfMem((APTR)0x090000);
if ((memtype & MEMF_CHIP) == MEMF_CHIP) { /* ... It's chip memory ... */ }
</syntaxhighlight>

TypeOfMem() returns the attributes of the memory at a specific address. If it is passed an invalid memory address, TypeOfMem() returns NULL. This routine is normally used to determine if a particular chunk of memory is in chip memory.

=== Using Memory Copy Functions ===

For memory block copies, the CopyMem() and CopyMemQuick() functions can be used.

==== Copying System Memory ====

The following samples show how to use the copying routines.

<syntaxhighlight>
APTR source = IExec->AllocVecTags(1000, AVT_ClearWithValue, 0, TAG_END);
APTR target = IExec->AllocVecTags(1000, AVT_Type, MEMF_SHARED, TAG_END);
IExec->CopyMem(source, target, 1000);
</syntaxhighlight>

CopyMem() copies the specified number of bytes from the source data region to the target data region. The pointers to the regions can be aligned on arbitrary address boundaries. CopyMem() will attempt to copy the memory as efficiently as it can according to the alignment of the memory blocks, and the amount of data that it has to transfer. These functions are optimized for copying large blocks of memory which can result in unnecessary overhead if used to transfer very small blocks of memory.

CopyMemQuick() is now identical to CopyMem(). In previous versions of the operating system, CopyMemQuick() performed more optimized copying of the specified number of bytes from the source data region to the target data region. The source and target pointers must be longword aligned and the size (in bytes) must be divisible by four. There are no such restrictions starting with AmigaOS 4.0.

{{Note|title=''Not All Copies Are Supported''|text=Neither CopyMem() nor CopyMemQuick() supports copying between regions that overlap. For overlapping regions see MoveMem() in the [[Utility Library]].}}

=== System Memory Pools ===

A construct carried over from the AmigaOS 3.x Exec is the memory pool. The code handling memory pools uses an algorithm based on boundary tags and size-segregated memory lists. The speed gain is tremendous: even for the "dumb" case of just allocating 100000 blocks and freeing them again, the speed is ten times faster than the previous implementation. Due to the size-segregated free lists and the easy coalescing due to the boundary tags, real-life performance gain is even higher and would be between 10 and 20 times.

Two types of memory pools are available depending on the needs of the application:
* [[Exec_Item_Pools|Item Pools]] are built for speed and are used for allocating large numbers of items that are all the same size.
* Generic [[Exec_Memory_Pools|Memory Pools]] can handle allocations of different sizes at the expense of some speed.

=== Summary of System Controlled Memory Handling Routines ===

; AllocVecTags() and FreeVec()
: These are system-wide memory allocation and deallocation routines. They use a memory free-list owned and managed by the system.

; LockMem() and UnlockMem()
: These routines explicitly lock and unlock underlying memory pages.

; AvailMem()
: This routine returns the number of free bytes in a specified type of memory.

; TypeOfMem()
: This routine returns the memory attributes of a specified memory address.

; CopyMem() and CopyMemQuick()
: CopyMem() is a general purpose memory copy routine. CopyMemQuick() is an optimized version of CopyMemQuick(), but has restrictions on the size and alignment of the arguments.

== Allocating DMA Memory ==

Device drivers often use DMA to transfer data to and from the device. The StartDMA(), GetDMAList() and EndDMA() functions are used to create a scatter/gather list suitable for such DMA transfers.

The following conditions are guaranteed to be met when using these DMA functions:
* The memory region given is guaranteed to be mapped to physical memory.
* The mapping will not change as long as EndDMA() is not called.
* All cache entries in this region will be flushed out.

The example code below demonstrates how to perform a DMA write transfer:

<syntaxhighlight>
APTR addr;
uint32 size;

/* Tell the system to prepare for DMA */
uint32 arraySize = IExec->StartDMA(addr, size, 0);
if (arraySize > 0)
{
/* The memory area is prepared, allocate and retrieve the DMA list */
struct DMAEntry *DMAList = IExec->AllocSysObject(ASOT_DMAENTRY,
ASODMAE_NumEntries, arraySize,
TAG_END);

if (DMAList != NULL)
{
IExec->GetDMAList(addr, size, 0, DMAList);

/* Feed the DMA controller and do stuff */
...
/* Get rid of the DMAList's memory */

IExec->EndDMA(addr, size, endFlags);
IExec->FreeSysObject(ASOT_DMAENTRY, DMAList);
}
else
{
// Note We still call EndDMA() even though the actual
// transfer didn't happen.
IExec->EndDMA(addr, size, DMAF_NoModify);

IDOS->Printf("Can't allocate DMA list\n");
}
}
else
{
IDOS->Printf("Can't initiate DMA transfer\n");
}
</syntaxhighlight>

== Syncing and Memory Access ==

The PowerPC is a pure load/store architecture. That means, it will never operate on memory arguments like x86, to modify data, you have to load, modify and store.

All PowerPC/POWER cpus have a load/store queue, i.e. a queue where load and store operations are queued to reduce memory latency. If more than one store is made to the same long word (i.e. you write the first byte and then the second byte), then those stores are combined. As you can see, this will cause a problem for a chip register since both are written at the same time which is likely not what you want.

Similar for reading: A read might shortcut through the load/store queue and use a value that's already been read and is present in the load/store queue. Again, for chip registers, this will cause a problem because you might read an old value.

There are two instructions that deal with this: '''eieio''' (Ensure In-order Execution of I/O) and '''sync'''.

The eieio instruction simply inserts a "barrier" into the load/store queue. When combining ''stores'' the CPU never searches past this barrier for possible combines. This means that the sequence

# store to some address
# eieio
# store to some address + 1

will never be combined because of the eieio barrier between them.

The sync instruction will simply halt all execution and flush the load/store queue, executing and finishing all loads and stores.

As you can imagine, sync is MUCH MORE costly than eieio.

=== When to use eieio and sync ===

If you want to write, post fix your writes with an eieio instruction.

If you want to read, prefix your reads with a sync instruction.

This is also where the "GUARDED" memory flag comes in. GUARDED memory simply ensures program order of loads and stores, that is, it's an implicit eieio.

{{Note|Knowing when and how to use the '''eieio''' and '''sync''' instructions is somewhat vital for driver developers.}}

== Allocating Multiple Memory Blocks ==

Exec provides the routines AllocTaskMemEntry() and FreeEntry() to allocate multiple memory blocks in a single call.

AllocTaskMemEntry() accepts a data structure called a MemList, which contains the information about the size of the memory blocks to be allocated and the requirements, if any, that you have regarding the allocation.

The MemList structure is found in the include file <exec/memory.h> and is defined as follows:

<syntaxhighlight>
struct MemList
{
struct Node ml_Node;
UWORD ml_NumEntries; /* number of MemEntrys */
struct MemEntry ml_ME[1]; /* where the MemEntrys begin*/
};
</syntaxhighlight>

; ml_Node
: allows you to link together multiple MemLists. However, the node is ignored by the routines AllocTaskMemEntry() and FreeEntry().

; ml_NumEntries
: tells the system how many MemEntry sets are contained in this MemList. Notice that a MemList is a variable-length structure and can contain as many sets of entries as you wish.

The MemEntry structure looks like this:

<syntaxhighlight>
struct MemEntry
{
union {
ULONG meu_Reqs; /* the AllocMem requirements */
APTR meu_Addr; /* address of your memory */
} me_Un;
ULONG me_Length; /* the size of this request */
};
</syntaxhighlight>

=== Sample Code for Allocating Multiple Memory Blocks ===

Here's an example of showing how to use the AllocTaskMemEntry() with multiple blocks of memory.

<syntaxhighlight>
// alloctaskmementry.c - example of allocating several memory areas.
#include <exec/types.h>
#include <exec/memory.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct MemList *memlist; /* pointer to a MemList structure */

struct MemBlocks /* define a new structure because C cannot initialize unions */
{
struct MemList mn_head; /* one entry in the header */
struct MemEntry mn_body[3]; /* additional entries follow directly as */
} memblocks; /* part of the same data structure */

int main()
{
memblocks.mn_head.ml_NumEntries = 4; /* 4! Since the MemEntry starts at 1! */

/* Describe the first piece of memory we want. Because of our MemBlocks structure */
/* setup, we reference the first MemEntry differently when initializing it. */
memblocks.mn_head.ml_ME[0].me_Reqs = MEMF_CLEAR;
memblocks.mn_head.ml_ME[0].me_Length = 4000;

memblocks.mn_body[0].me_Reqs = MEMF_PRIVATE | MEMF_CLEAR;/* Describe the other pieces of */
memblocks.mn_body[0].me_Length = 100000; /* memory we want. Additional */
memblocks.mn_body[1].me_Reqs = MEMF_SHARED | MEMF_CLEAR; /* MemEntries are initialized this */
memblocks.mn_body[1].me_Length = 200000; /* way. If we wanted even more en- */
memblocks.mn_body[2].me_Reqs = MEMF_EXECUTABLE; /* tries, we would need to declare */
memblocks.mn_body[2].me_Length = 25000; /* a larger MemEntry array in our */
/* MemBlocks structure. */

memlist = (struct MemList *)IExec->AllocTaskMemEntry((struct MemList *)&memblocks);

if (memlist == NULL)
{
IDOS->Printf("AllocTaskMemEntry FAILED\n");
return RETURN_FAIL;
}

/* We got all memory we wanted. Use it and call FreeEntry() to free it */
IDOS->Printf("AllocTaskMemEntry succeeded - now freeing all allocated blocks\n");
IExec->FreeEntry(memlist);

return 0;
}
</syntaxhighlight>

AllocTaskMemEntry() returns a pointer to a new MemList of the same size as the MemList that you passed to it. For example, ROM code can provide a MemList containing the requirements of a task and create a RAM-resident copy of the list containing the addresses of the allocated entries. The pointer to the MemList is used as the argument for FreeEntry() to free the memory blocks.

=== Result of Allocating Multiple Memory Blocks ===

The MemList created by AllocTaskMemEntry() contains MemEntry entries. MemEntrys are defined by a union statement, which allows one memory space to be defined in more than one way.

If AllocTaskMemEntry() returns a non-NULL value then all of the meu_Addr positions in the returned MemList will contain valid memory addresses meeting the requirements you have provided. To use this memory area, you would use code similar to the following:

<syntaxhighlight>
struct MemList *mlist = IExec->AllocTaskMemEntry(&ML);
APTR memory = NULL;

if ( mlist != NULL )
{
memory = mlist->ml_ME[0].me_Un.meu_Addr;
}
</syntaxhighlight>

=== Multiple Memory Blocks and Tasks ===

If you want to take advantage of Exec's automatic cleanup, use the MemList and AllocTaskMemEntry() facility to do your dynamic memory allocation.

In the Task control block structure, there is a list header named tc_MemEntry.

This is the list header that you initialize to include MemLists that your task has created by call(s) to AllocTaskMemEntry(). Here is a short program segment that handles task memory list header initialization only. It assumes that you have already run AllocTaskMemEntry() as shown in the simple AllocTaskMemEntry() example above.

<syntaxhighlight>
struct MemList *ml;

struct Task *tc = IExec->FindTask(0);

IExec->AddTail(tc->tc_MemEntry, ml);
</syntaxhighlight>

Assuming that you have only used the AllocTaskMemEntry() method (or AllocVecTags() and built your own custom MemList), the system now knows where to find the blocks of memory that your task has dynamically allocated. The RemTask() function automatically frees all memory found on tc_MemEntry.

{{Note|title=''CreateTask() Sets Up A MemList.''|text=The CreateTask() function, and other system task and process creation functions use a MemList in tc_MemEntry so that the Task structure and stack will be automatically deallocated when the Task is removed.}}

=== Summary of Multiple Memory Blocks Allocation Routines ===

These are routines for allocating and freeing multiple memory blocks with a single call.

This routine initializes memory from data and offset values in a table. Typically only assembly language programs benefit from using this routine. See the SDK for more details.

== Allocating Memory at an Absolute Address ==

For special advanced applications, AllocAbs() is provided. Using AllocAbs(), an application can allocate a memory block starting at a specified absolute memory address. If the memory is already allocated or if there is not enough memory available for the request, AllocAbs() returns a zero.

Be aware that an absolute memory address which happens to be available on one Amiga may not be available on a machine with a different configuration or different operating system revision, or even on the same machine at a different times. For example, a piece of memory that is available during expansion board configuration might not be available at earlier or later times. Here is an example call to AllocAbs():

<syntaxhighlight>
APTR absoluteptr = (APTR)IExec->AllocAbs(10000, 0x2F0000);
if (!(absoluteptr))
{ /* Couldn't get memory, act accordingly. */ }

/* After we're done using it, we call FreeMem() to free the memory block. */
IExec->FreeMem(absoluteptr, 10000);
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the Exec functions that handle memory management. See the SDK for details on each call.

{| class="wikitable"
! Memory Function
! Description
|-
| AllocMem()
| Allocate memory with specified attributes. '''This function is obsolete.'''
|-
| AllocAbs()
| Allocate memory at a specified location.
|-
| AllocTaskMemEntry()
| Allocate multiple memory blocks.
|-
| AllocVec()
| Allocate memory with specified attributes and keep track of the size. This function is obsolete.
|-
| AllocVecTags()
| Allocate memory with specified attributes defined by tags and keep track of the size. If an application needs to allocate some memory, it will usually use this function.
|-
| AvailMem()
| Return the amount of free memory, given certain conditions.
|-
| CopyMem()
| Copy memory block, which can be non-aligned and of arbitrary length.
|-
| CopyMemQuick()
| Copy aligned memory block.
|-
| FreeEntry()
| Free multiple memory blocks, allocated with AllocTaskMemEntry().
|-
| FreeMem()
| Free a memory block of specified size, allocated with AllocMem() or AllocAbs().
|-
| FreeVec()
| Free a memory block allocated with AllocVecTags() or AllocVec().
|-
| InitStruct()
| Initialize memory from a table.
|-
| LockMem()
| Lock the underlying pages given a memory block address and size.
|-
| TypeOfMem()
| Determine attributes of a specified memory address.
|-
| UnlockMem()
| Unlock the underlying pages given a memory block address and size.
|}

Exec Memory Allocation

2023-11-25T16:02:56Z

Ryan Dixon: Minor grammar

== Exec Memory Allocation ==

Exec manages all of the free memory currently available in the system. Using a slab allocation system, Exec keeps track of memory and provides the functions to allocate and access it.

When an application needs some memory, it can either declare the memory statically within the program or it can ask Exec for some memory. When Exec receives a request for memory, it searches its free memory regions to find a suitably sized block that matches the size and attributes requested.

Prior to AmigaOS 4.0, the OS did not make use of the CPU's memory management unit and used memory "as-is". That is, if you have different memory expansions plugged into your system, the memory will be seen as chunks located somewhere in the 4 gigabyte address space. Since version 4.0, the MMU will be used to "map" memory pages from their physical location to a virtual address. There are multiple reasons why this is better than using the verbatim physical addresses - among other things it reduces the effect of "memory fragmentation" and simplifies the possibility to swap currently unused memory pages to persistent storage such as a hard disk.

The "downside" is that the virtual address of a memory block is almost never identical to the physical address. This isn't much of a downside, since an application will never really need to care about it. If an application allocates a block of memory of n bytes, it will get a pointer back that points to at least n continuous addresses as expected. The pages that "fill" this memory block may come from different physical locations scattered throughout the physical memory but a program will never noticed that. For all intent and purpose, the application sees a single continuous block of memory.

=== Program Address Space ===

It is important to remember that, just like in classic AmigaOS, a single address space is used for all programs. Sometimes the mention of an MMU can lead people to assume that each process on the Amiga will have its own personal, partitioned address space. The following two programs demonstrate that, even though they are separate processes, it is possible to read and write another's memory. The memory locations are the same virtual address and that virtual address maps onto the same physical address.

This program has a global variable. It prints out the virtual address of the global, the value at that address (which can be optionally specified), waits for a keypress and, finally, prints out the value at that same address again in case it has been externally updated (which is done by the subsequent program listing):
<pre>
#include <stdlib.h>
#include <stdio.h>

volatile char x = 127;

/* Usage: a [VAL] */
int main(int argc, char *argv[])
{
if(argc==2)
x = (char)atoi(argv[1]);

printf("Virtual Address of `x': %p\n", (void*)&x);
printf("Dereferenced Value of `x': %d\n", x);
(void)getchar();
printf("Final Value of `x': %d\n", x);
return 0;
}
</pre>

This program reads in an address as an argument and prints the value at that address even though it does not "own" the memory. By adding an additional argument, this program can also write to that "foreign" address. After this program is complete, you can press a key on the previous program and see that the value changed:
<pre>
#include <stdlib.h>
#include <stdio.h>

/* Usage: b ADDR [VAL_TO_WRITE] */
int main(int argc, char *argv[])
{
if(!(argc==2 || argc==3))
return 10;

volatile char *byte = (volatile char*)strtol(argv[1],NULL,16);
printf("Selected Virtual Address : %p\n",(void*)byte);
printf("Dereferenced Value of Address: %d\n",*byte);
if(argc==3)
{
printf("Writing Value `%d' to Address: %p\n",atoi(argv[2]),(void*)byte);
*byte=(char)atoi(argv[2]);
}

return 0;
}
</pre>

=== Slab allocation ===

[[File:SlabDiagram.jpg|right]]

The AmigaOS memory architecture is based on the "slab allocator" system or "object cache". In essence, the slab allocator only allocates objects of a single size, allocating these in larger batches ("slabs") from the low-level page allocator. These slabs are then divided up into buffers of the required size, and kept within a list in the slab allocator.

Allocating an object with the slab allocator becomes a process of simple node removal: the first node in the first slab containing free nodes is removed and returned for use. Since the slab allocator keeps free slabs or partially free slabs in a separate list from the full slabs, this operation can be carried out in constant time. Freeing memory is accomplished by returning the buffer to its cache, and adding it to its original slab's free list. Slabs that are completely free can be returned to the system's page pool (this operation is actually driven by demand, and timestamps are used to avoid unnecessary loading of data, or "thrashing"). External fragmentation is minimal, and internal fragmentation is controlled and guaranteed not to exceed a certain amount.

=== Object caching ===

The slab allocator can also be used to cache objects. In the real world a lot of memory allocation operations will be used to allocate the same object. The system has a number of data structures which are allocated frequently (semaphores, message ports and the like). Every time such structures are allocated, they must be initialised, and when they are deleted again, they must be cleaned up. It's likely, however, that such a structure will be needed again in the future, so that it can be kept in its initialised state and re-used later. This further reduces the load on the allocator routines, and thus improves system performance.

The object caches work on memory that has already been mapped into the virtual memory space.

=== More Advantages ===

Another advantage is the possibility to improve CPU cache usage. Usually, most objects have "hot spots", i.e. they have a few fields that are used often. Since most of the time a little memory is left unused in a slab (the object size might not be a multiple of the slab size), this additional memory can be used to "shift" the hot spots by a few bytes to optimise the memory structure, leading to better cache usage.

Finally, the system can be expanded to multiple CPUs with next to no overhead. On multi-CPU system, these expanded slab allocators scale almost linearly with the number of CPUs employed, making it the ideal choice for such systems.

The combination of object caching and keeping caches for different memory blocks (for AllocVec/FreeVec emulation) makes the memory management more efficient, faster, and generally more future-proof than the old free list approach used in AmigaOS 3.x and earlier.

See Wikipedia for more information on [http://en.wikipedia.org/wiki/Slab_allocation slab allocator systems].

=== Physical page allocation ===

Every memory location in a computer system has its own, unique address. That is, there is a byte location at address x where you can store and retrieve a single byte. This address is fixed; there is no way to change it without physically changing the hardware. Therefore, this address is called the “physical” address.

The physical address of a memory page is most often completely irrelevant to the application. The CPU will typically only see the virtual address. AmigaOS will take care of assigning virtual addresses to memory paging. This is often called “mapping” a page. Only in very special cases will the physical address be relevant. For example, device drivers that want to pass memory to a hardware device via DMA. Since the MMU is part of the CPU, any external hardware like an IDE controller will not see the virtual but only physical addresses.

A common operation in memory allocation is the assignment of virtual addresses to physical memory locations. Allocation of physical memory is usually done differently from virtual allocations, since it's necessary to free up only part of the allocation (when for example the pager kicks in).

The de-facto standard in allocation of physical pages is a method invented by Knuth, called [http://en.wikipedia.org/wiki/Buddy_memory_allocation the "buddy system"]. Basically every modern operating system uses it and AmigaOS is no exception.

Buddy systems are in essence size-segregated free lists. To allocate, the system searches for a free block of at least the size of the allocation. Then, if the block is too large, it's split into two even-sized blocks. These blocks are called "buddies". One block is returned to it's appropriate free list, and the other is considered further, maybe splitting it further until it's size matches that of the allocation.

In a buddy system, it's easy to determine whether the "buddy" is free or not, because it's address can simply be decided based on the address of the block to be freed.

=== Virtual address space allocation ===

Most CPUs come with a special unit that is called a "memory management unit" or "MMU" for short. The MMU's primary job is to rearrange the physical memory within the 4 gigabytes of address space in a way that is convenient for the operating system and/or applications. To do that effectively, it divides the memory into blocks (called "pages"). For every page the MMU has an entry in a table that specifies where the CPU should "see" this page, and what special attributes the page has. The address where the CPU "sees" this page is a 32 bit address as well, but since the memory is not really located there, we call that a "virtual" address.

AmigaOS uses a resource map allocator for allocating virtual address space. Basically this is a means of managing a set of resources (not necessarily memory). For performance reason, it uses several optimization techniques.

For one, all free resource blocks are held in space-segregated lists, i.e. there is a list for each power-of-two resource group. This makes allocations a lot faster by providing an upper and lower bound for a search. For example, if you want to allocate a block of 2^10 bytes, you can basically skip searching any block below 2^10 bytes in size simply because it won't fit. Similarly, you don't need to search for blocks that are larger than, say, twice the size of the block, since there might still be blocks of a size near to what we need. Size-segregated free lists help narrow down the search, making the search itself faster and the result better in terms of fragmentation.

In addition, the resource maps use object caches for accelerating "small" allocations. Most allocations are below a certain size. For example, the virtual addresses are always allocated in chunks of at least one "page" in memory (4096 bytes). So it's common to allocate blocks of one, two, four, or eight pages. The object caches provide an easy method for keeping these common sizes, making every allocation of these sizes an exact fit, further reducing fragmentation.

=== Page cache ===

A lot of the time spent in allocating memory was spent looking for the appropriate pages in memory. A 256 MB memory system has 65536 4KB pages. These pages have to be searched for from time to time. Originally, hash tables were used but it turned out that distributing 65536 page entries over a few hash buckets still produced lists of several thousand pages that had to be traversed to find a page. The hash table was replaced with a radix tree. These trees are rather broad, but shallow, making traversal very fast. In usual circumstances, the tree does not grow more than 4 to 5 levels in depth, making searching of a page a matter of maximum 4 to 5 compare operations.

=== Pager ===

AmigaOS has the possibility to swap out parts of memory to disk in order to free up more memory for other applications. This feature allows applications to use more memory than is actually physically installed in the system.

Paging is commonly referred to as "virtual memory" by users and sometimes even software developers. The fact AmigaOS uses virtual memory does not imply the use of the pager.

The system can be tuned to different strategies, either page out only on demand (for highly interactive tasks), or based on other needs (lots of free memory in core for disk caches etc.).

The optimized data structures allow the memory system to operate at a very high speed.

The time for a memory allocation is now in the order of a few microseconds. This is especially true for small allocation (below 8096 bytes). During system testing it was observed that by the time the system has booted up to Workbench, there have already been 40,000 allocations to the global memory pool below 2096 bytes.

== Memory Functions ==

Normally, an application uses the AllocVecTags() function to ask for memory:

<syntaxhighlight>
void *AllocVecTags(uint32 size, uint32 tag1, ...);
</syntaxhighlight>

The size argument is the amount of memory the application needs and the tag list specifies the type of memory and any special memory characteristics (described later). If AllocVecTags() is successful, it returns a pointer to a block of memory. The memory allocation will fail if the system cannot find a big enough block with the requested attributes. If AllocVecTags() fails, it returns NULL.

Because the system only keeps track of how much free memory is available and not how much is in use, it has no idea what memory has been allocated by any task. This means an application has to explicitly return, or deallocate, any memory it has allocated so the system can reuse it. If an application does not return a block of memory to the system, the system will not be able to reallocate that memory to some other task. That block of memory will be lost until the Amiga is reset. If you are using AllocVecTags() to allocate memory, a call to FreeVec() will return that memory to the system:

<syntaxhighlight>
void FreeVec(void *memoryBlock);
</syntaxhighlight>

Here memoryBlock is a pointer to the memory block the application is returning to the system. The size of the memory block is tracked internally by the system.

Unlike some compiler memory allocation functions, the Amiga system memory allocation functions return memory blocks that are at least longword aligned. This means that the allocated memory will always start on an address which is at least evenly divisible by four. This alignment makes the memory suitable for any system structures or buffers which require word or long word alignment, and also provides optimal alignment for stacks and memory copying.

=== Memory Types ===

There are three primary types of memory in AmigaOS which are summarized in the following table:

{| class="wikitable"
! Type
! Use
|-
| MEMF_PRIVATE
| This memory is private and only accessible within the context of the Task which allocated it. Private memory should always be preferred. Private memory is also swappable by default (i.e. not locked). This memory will not be visible to any other address space.
In a future version of AmigaOS, it is planned to have Task specific address spaces. This means each task could potentially address up to 4 GB of private memory each.
|-
| MEMF_SHARED
| The memory is shared and accessible by any Task in the system without restriction. This memory can be shared between all address spaces and will always appear at the same address in any address space. Shared memory is locked by default and thus is not swappable.
|-
| MEMF_EXECUTABLE
| The memory is used to store executable PowerPC code. This is used two-fold in AmigaOS. First, it allows the system to determine if a function pointer points to real native PowerPC code as opposed to 68k code which needs to be emulated. Second, it prevents common exploits that use stack overflows to execute malicious code. Executable memory is locked by default and thus is not swappable.
|}

=== Memory Attributes ===

Memory allocation on AmigaOS has traditionally been rather complicated. Over time, as new hardware models were released, more memory attribute flags were introduced.

All the various memory allocation functions and strategies have been consolidated and distilled into a single AllocVecTags() function call. Programmers are strongly encouraged to stop using any other function to allocate system memory. Using AllocVecTags() is the only way to guarantee future compatibility with more advanced AmigaOS features yet to come.

If an application does not specify any attributes when allocating memory, the system tries to satisfy the request with the fastest memory available on the system memory lists.

{{Note|title=Make Sure You Have Memory|text=Always check the result of any memory allocation to be sure the type and amount of memory requested is available. Failure to do so will lead to trying to use an non-valid pointer.}}

==== Using Tags ====

The AllocVecTags() function uses a tag list to define what attributes a block of memory must have. The currently supported tags are listed below.

{| class="wikitable"
! Tag (Default)
! Description
|-
| rowspan="4" | AVT_Type
(MEMF_PRIVATE)
|-
| MEMF_PRIVATE: Allocate from the task private heap. This memory will not be visible to any other address space.
|-
| MEMF_SHARED: Allocate from the system shared heap. This memory can be shared between all address spaces and will always appear at the same address in any address space. This memory is locked by default (see AVT_Lock tag below).
|-
| MEMF_EXECUTABLE: Allocate memory that is marked executable. This memory is locked by default (see AVT_Lock tag below).
|-
| AVT_Contiguous
(FALSE)
| Memory allocated with this property is allocated from a contiguous block of physical memory. This makes the memory suitable for DMA purposes when the DMA device does not support scatter/gather operation. For devices that do support scatter/gather use StartDMA() instead.
''Note:'' Physical pages can move at any time, be removed from memory due to paging or otherwise made unavailable unless the memory pages are locked (see LockMemory() function or AVT_Lock tag).
|-
| AVT_Lock
(TRUE or FALSE)
| After allocating memory, lock the associated pages in memory. This will prevent the pages from being moved, swapped out or otherwise being made unavailable. This is useful in conjunction with the AVT_Contiguous tag since it will ensure that the memory will stay contiguous after allocation.
This tag defaults to FALSE for MEMF_PRIVATE allocations and to TRUE for MEMF_SHARED or MEMF_EXECUTABLE.
|-
| AVT_Alignment
(16)
| Define an alignment constraint for the allocated memory block. The returned memory block will be aligned to the given size (in bytes). It's virtual address will be at least a multiple of the AVT_Alignment value.
''Note:'' Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_PhysicalAlignment
(16)
| Define an alignment constraint for the allocated memory block physical address. See AVT_Alignment for more information.
''Note:'' This functionality is mainly used for DMA drivers that require a specific alignment. Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_ClearWithValue
| Clear the newly allocated memory with the given byte value. If this tag is not given the memory block is not cleared.
|-
| AVT_Wait
(TRUE)
| Wait for the memory subsystem to be available. If TRUE, the calling task will be retired until the memory subsystem is available. This might cause a Forbid() to break. When FALSE and the memory subsystem is not currently available, the function will return immediately and the allocation will fail.
|-
| AVT_NoExpunge
(FALSE)
| If allocation fails because of unavailability, prevent invocation of low memory cleanup handlers. The default is FALSE which means that when memory is not available, cleanup handlers are invoked to try and satisfy the allocation.
|}

==== Using Flags ====

The use of memory flags was the only supported way to allocate memory prior to AmigaOS 4.0. It may be still useful to know more about this obsolete system for porting older applications. For more information about the memory flags system see [[Obsolete Exec Memory Allocation]].

=== Allocating System Memory ===

The following examples show how to allocate memory.

<syntaxhighlight>
APTR apointer = IExec->AllocVecTags(100, TAG_END);

if (apointer == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

AllocVecTags() returns the address of the first byte of a memory block that is at least 100 bytes in size or NULL if there is not that much free memory. Because there are no tags specified, private memory is assumed so this memory cannot be shared with any other tasks.

In addition to allocating a block of memory, this function keeps track of the size of the memory block, so your application doesn't have to remember it when it deallocates that memory block. The AllocVecTags() function allocates a little more memory to store the size of the memory allocation request.

{{Note|title=Make No Assumptions|It is not legal to peek the longword in front of the returned memory pointer to find out how big the block is. This has always been illegal regardless of what any other documentation may have stated to the contrary. Your application has access to the memory returned by AllocVecTags() and the only guarantee made is that the returned block has n bytes of continuous address space starting at the returned address. Anything outside this area is not to be touched.}}

<syntaxhighlight>
APTR anotherptr = IExec->AllocVecTags(1000,
AVT_Type, MEMF_SHARED,
AVT_Lock, FALSE,
AVT_ClearWithValue, 0,
TAG_END);

if (anotherptr == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocates shared memory which is accessible by any task in the system and clears the memory contents to zero. MEMF_SHARED memory is locked by default for compatibility with the obsolete MEMF_PUBLIC flag. This is by far the most common case when allocating shared memory.

<syntaxhighlight>
APTR lockedmem = IExec->AllocVecTags(3000,
AVT_Type, MEMF_SHARED,
TAG_END);

if (lockedmem == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocated shared memory which is accessible by any task in the system. MEMF_SHARED memory is locked by default so the underlying memory pages are not moveable and cannot be swapped out. Such memory could be used to share memory between a Process and an interrupt routine for example.

If the system free memory list does not contain enough contiguous memory bytes in an area matching your requirements, AllocVecTags() returns a zero. You ''must'' check for this condition.

<syntaxhighlight>
APTR yap = IExec->AllocVec(500, MEMF_CHIP);

if (yap == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The deprecated AllocVec() function is used in the example above because it is the only way to allocate MEMF_CHIP memory on a classic Amiga system.

=== Locking System Memory ===

The LockMem() function is used to explicitly lock a memory block. This function will make sure your memory block is not unmapped, swapped out or somehow made inaccessible. Use this function wisely. If there is no good reason to lock memory then do not do it. It will prevent the memory system from optimizing memory layout and may lead to poor performance.

<syntaxhighlight>
IExec->LockMem(mem, 1000);
</syntaxhighlight>

Before deallocating the memory is must be unlocked as well.

<syntaxhighlight>
IExec->UnLockMem(mem, 1000);
</syntaxhighlight>

{{Note|title=''Do not forget to UnlockMem()''|Failure to unlock memory will have adverse affects on the memory system. Locked memory pages cannot be moved so the system cannot optimize the layout of locked memory pages.}}

Be careful to always match the number of locks and the number of unlocks. If something else may have locked memory in the same page and an extraneous UnlockMem() decreases the lock reference counter to 0, that page can be paged out or moved. If that happens, for example, with data used in an interrupt handler or by the device driver which handles the swap partition the system will crash.

=== Freeing System Memory ===

The following examples free the memory chunks shown in the previous calls to AllocVecTags().

<syntaxhighlight>
IExec->FreeVec(apointer);

IExec->FreeVec(anotherptr);

IExec->FreeVec(lockedmem);

IExec->FreeVec(yap);
</syntaxhighlight>

A memory block allocated with AllocVecTags() or AllocVec() must be returned to the system pool with the FreeVec() function. This function uses the stored size in the allocation to free the memory block, so there is no need to specify the size of the memory block to free.

Any memory that is locked must be explicitly unlocked with UnlockMem() prior to freeing it. Failure to unlock memory will not cause any immediate problems but any pages which are locked cannot be moved or swapped out which can decrease system performance. Never unlock memory which has not been explicitly locked with LockMem() as it could lead to undefined behaviour.

FreeVec() returns no status. However, if you attempt to free a memory block in the middle of a chunk that the system believes is already free, you will cause a system crash. It is also illegal to free the same memory block twice and this will lead to a system crash.

{{Note|title=''Leave Memory Allocations Out Of Interrupt Code''|text=Do not allocate or deallocate system memory from within interrupt code. The [[Exec_Interrupts|Exec Interrupts]] section explains that an interrupt may occur at any time, even during a memory allocation process. As a result, system data structures may not be internally consistent at this time.}}

=== Memory may be Locked by Default ===

By default, the system memory allocation routines will allocate MEMF_SHARED and MEMF_EXECUTABLE memory and implicitly lock it. This memory must not be explicitly unlocked. Let the system handle the unlocking internally.

Here is the right way to allocate and free MEMF_SHARED memory:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->FreeVec(ptr);
</syntaxhighlight>

Here is the wrong way:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->UnlockMem(ptr, 10); // Doing this could lead to undefined system behaviour.
IExec->FreeVec(ptr);
</syntaxhighlight>

Unlocking memory not explicitly locked does not immediately cause any issues. However, in a future version of AmigaOS the memory pages may be handled differently than they are handled today. This could lead to incompatibilities with your applications and AmigaOS. The simple rule is that if you called LockMem() you must also call UnlockMem(). All other times you should not call UnlockMem().

{{Note|Memory locking is done at the page level. Even if a single byte of memory is locked in a page that entire page is locked. The programmer has no control over which pages may be used to satisfy a memory allocation.}}

{{Note|Shared and executable memory is locked implicitly for 68K backwards compatibility reasons. Use AVT_Lock (or equivalent) to ensure your shared and executable memory is not locked. MEMF_PRIVATE memory has no backwards compatibility issues and is always unlocked by default.}}

=== Memory Information Functions ===

The memory information routines AvailMem() and TypeOfMem() can provide the amount of memory available in the system, and the attributes of a particular block of memory.

==== Memory Requirements ====

The same attribute flags used in memory allocation routines are valid for the memory information routines. There is also an additional flag, MEMF_LARGEST, which can be used in the AvailMem() routine to find out what the largest available memory block of a particular type is. Specifying the MEMF_TOTAL flag will return the total amount of memory currently available.

==== Calling Memory Information Functions ====

The following example shows how to find out how much memory of a particular type is available.

<syntaxhighlight>
uint32 size = IExec->AvailMem(MEMF_CHIP | MEMF_LARGEST);
</syntaxhighlight>

AvailMem() returns the size of the largest chunk of available chip memory.

{{Note|title=''AvailMem() May Not Be Totally Accurate''|text=Because of multitasking, the return value from AvailMem() may be inaccurate by the time you receive it.}}

The following example shows how to determine the type of memory of a specified memory address.

<syntaxhighlight>
uint32 memtype = IExec->TypeOfMem((APTR)0x090000);
if ((memtype & MEMF_CHIP) == MEMF_CHIP) { /* ... It's chip memory ... */ }
</syntaxhighlight>

TypeOfMem() returns the attributes of the memory at a specific address. If it is passed an invalid memory address, TypeOfMem() returns NULL. This routine is normally used to determine if a particular chunk of memory is in chip memory.

=== Using Memory Copy Functions ===

For memory block copies, the CopyMem() and CopyMemQuick() functions can be used.

==== Copying System Memory ====

The following samples show how to use the copying routines.

<syntaxhighlight>
APTR source = IExec->AllocVecTags(1000, AVT_ClearWithValue, 0, TAG_END);
APTR target = IExec->AllocVecTags(1000, AVT_Type, MEMF_SHARED, TAG_END);
IExec->CopyMem(source, target, 1000);
</syntaxhighlight>

CopyMem() copies the specified number of bytes from the source data region to the target data region. The pointers to the regions can be aligned on arbitrary address boundaries. CopyMem() will attempt to copy the memory as efficiently as it can according to the alignment of the memory blocks, and the amount of data that it has to transfer. These functions are optimized for copying large blocks of memory which can result in unnecessary overhead if used to transfer very small blocks of memory.

CopyMemQuick() is now identical to CopyMem(). In previous versions of the operating system, CopyMemQuick() performed more optimized copying of the specified number of bytes from the source data region to the target data region. The source and target pointers must be longword aligned and the size (in bytes) must be divisible by four. There are no such restrictions starting with AmigaOS 4.0.

{{Note|title=''Not All Copies Are Supported''|text=Neither CopyMem() nor CopyMemQuick() supports copying between regions that overlap. For overlapping regions see MoveMem() in the [[Utility Library]].}}

=== System Memory Pools ===

A construct carried over from the AmigaOS 3.x Exec is the memory pool. The code handling memory pools uses an algorithm based on boundary tags and size-segregated memory lists. The speed gain is tremendous: even for the "dumb" case of just allocating 100000 blocks and freeing them again, the speed is ten times faster than the previous implementation. Due to the size-segregated free lists and the easy coalescing due to the boundary tags, real-life performance gain is even higher and would be between 10 and 20 times.

Two types of memory pools are available depending on the needs of the application:
* [[Exec_Item_Pools|Item Pools]] are built for speed and are used for allocating large numbers of items that are all the same size.
* Generic [[Exec_Memory_Pools|Memory Pools]] can handle allocations of different sizes at the expense of some speed.

=== Summary of System Controlled Memory Handling Routines ===

; AllocVecTags() and FreeVec()
: These are system-wide memory allocation and deallocation routines. They use a memory free-list owned and managed by the system.

; LockMem() and UnlockMem()
: These routines explicitly lock and unlock underlying memory pages.

; AvailMem()
: This routine returns the number of free bytes in a specified type of memory.

; TypeOfMem()
: This routine returns the memory attributes of a specified memory address.

; CopyMem() and CopyMemQuick()
: CopyMem() is a general purpose memory copy routine. CopyMemQuick() is an optimized version of CopyMemQuick(), but has restrictions on the size and alignment of the arguments.

== Allocating DMA Memory ==

Device drivers often use DMA to transfer data to and from the device. The StartDMA(), GetDMAList() and EndDMA() functions are used to create a scatter/gather list suitable for such DMA transfers.

The following conditions are guaranteed to be met when using these DMA functions:
* The memory region given is guaranteed to be mapped to physical memory.
* The mapping will not change as long as EndDMA() is not called.
* All cache entries in this region will be flushed out.

The example code below demonstrates how to perform a DMA write transfer:

<syntaxhighlight>
APTR addr;
uint32 size;

/* Tell the system to prepare for DMA */
uint32 arraySize = IExec->StartDMA(addr, size, 0);
if (arraySize > 0)
{
/* The memory area is prepared, allocate and retrieve the DMA list */
struct DMAEntry *DMAList = IExec->AllocSysObject(ASOT_DMAENTRY,
ASODMAE_NumEntries, arraySize,
TAG_END);

if (DMAList != NULL)
{
IExec->GetDMAList(addr, size, 0, DMAList);

/* Feed the DMA controller and do stuff */
...
/* Get rid of the DMAList's memory */

IExec->EndDMA(addr, size, endFlags);
IExec->FreeSysObject(ASOT_DMAENTRY, DMAList);
}
else
{
// Note We still call EndDMA() even though the actual
// transfer didn't happen.
IExec->EndDMA(addr, size, DMAF_NoModify);

IDOS->Printf("Can't allocate DMA list\n");
}
}
else
{
IDOS->Printf("Can't initiate DMA transfer\n");
}
</syntaxhighlight>

== Syncing and Memory Access ==

The PowerPC is a pure load/store architecture. That means, it will never operate on memory arguments like x86, to modify data, you have to load, modify and store.

All PowerPC/POWER cpus have a load/store queue, i.e. a queue where load and store operations are queued to reduce memory latency. If more than one store is made to the same long word (i.e. you write the first byte and then the second byte), then those stores are combined. As you can see, this will cause a problem for a chip register since both are written at the same time which is likely not what you want.

Similar for reading: A read might shortcut through the load/store queue and use a value that's already been read and is present in the load/store queue. Again, for chip registers, this will cause a problem because you might read an old value.

There are two instructions that deal with this: '''eieio''' (Ensure In-order Execution of I/O) and '''sync'''.

The eieio instruction simply inserts a "barrier" into the load/store queue. When combining ''stores'' the CPU never searches past this barrier for possible combines. This means that the sequence

# store to some address
# eieio
# store to some address + 1

will never be combined because of the eieio barrier between them.

The sync instruction will simply halt all execution and flush the load/store queue, executing and finishing all loads and stores.

As you can imagine, sync is MUCH MORE costly than eieio.

=== When to use eieio and sync ===

If you want to write, post fix your writes with an eieio instruction.

If you want to read, prefix your reads with a sync instruction.

This is also where the "GUARDED" memory flag comes in. GUARDED memory simply ensures program order of loads and stores, that is, it's an implicit eieio.

{{Note|Knowing when and how to use the '''eieio''' and '''sync''' instructions is somewhat vital for driver developers.}}

== Allocating Multiple Memory Blocks ==

Exec provides the routines AllocTaskMemEntry() and FreeEntry() to allocate multiple memory blocks in a single call.

AllocTaskMemEntry() accepts a data structure called a MemList, which contains the information about the size of the memory blocks to be allocated and the requirements, if any, that you have regarding the allocation.

The MemList structure is found in the include file <exec/memory.h> and is defined as follows:

<syntaxhighlight>
struct MemList
{
struct Node ml_Node;
UWORD ml_NumEntries; /* number of MemEntrys */
struct MemEntry ml_ME[1]; /* where the MemEntrys begin*/
};
</syntaxhighlight>

; ml_Node
: allows you to link together multiple MemLists. However, the node is ignored by the routines AllocTaskMemEntry() and FreeEntry().

; ml_NumEntries
: tells the system how many MemEntry sets are contained in this MemList. Notice that a MemList is a variable-length structure and can contain as many sets of entries as you wish.

The MemEntry structure looks like this:

<syntaxhighlight>
struct MemEntry
{
union {
ULONG meu_Reqs; /* the AllocMem requirements */
APTR meu_Addr; /* address of your memory */
} me_Un;
ULONG me_Length; /* the size of this request */
};
</syntaxhighlight>

=== Sample Code for Allocating Multiple Memory Blocks ===

Here's an example of showing how to use the AllocTaskMemEntry() with multiple blocks of memory.

<syntaxhighlight>
// alloctaskmementry.c - example of allocating several memory areas.
#include <exec/types.h>
#include <exec/memory.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct MemList *memlist; /* pointer to a MemList structure */

struct MemBlocks /* define a new structure because C cannot initialize unions */
{
struct MemList mn_head; /* one entry in the header */
struct MemEntry mn_body[3]; /* additional entries follow directly as */
} memblocks; /* part of the same data structure */

int main()
{
memblocks.mn_head.ml_NumEntries = 4; /* 4! Since the MemEntry starts at 1! */

/* Describe the first piece of memory we want. Because of our MemBlocks structure */
/* setup, we reference the first MemEntry differently when initializing it. */
memblocks.mn_head.ml_ME[0].me_Reqs = MEMF_CLEAR;
memblocks.mn_head.ml_ME[0].me_Length = 4000;

memblocks.mn_body[0].me_Reqs = MEMF_PRIVATE | MEMF_CLEAR;/* Describe the other pieces of */
memblocks.mn_body[0].me_Length = 100000; /* memory we want. Additional */
memblocks.mn_body[1].me_Reqs = MEMF_SHARED | MEMF_CLEAR; /* MemEntries are initialized this */
memblocks.mn_body[1].me_Length = 200000; /* way. If we wanted even more en- */
memblocks.mn_body[2].me_Reqs = MEMF_EXECUTABLE; /* tries, we would need to declare */
memblocks.mn_body[2].me_Length = 25000; /* a larger MemEntry array in our */
/* MemBlocks structure. */

memlist = (struct MemList *)IExec->AllocTaskMemEntry((struct MemList *)&memblocks);

if (memlist == NULL)
{
IDOS->Printf("AllocTaskMemEntry FAILED\n");
return RETURN_FAIL;
}

/* We got all memory we wanted. Use it and call FreeEntry() to free it */
IDOS->Printf("AllocTaskMemEntry succeeded - now freeing all allocated blocks\n");
IExec->FreeEntry(memlist);

return 0;
}
</syntaxhighlight>

AllocTaskMemEntry() returns a pointer to a new MemList of the same size as the MemList that you passed to it. For example, ROM code can provide a MemList containing the requirements of a task and create a RAM-resident copy of the list containing the addresses of the allocated entries. The pointer to the MemList is used as the argument for FreeEntry() to free the memory blocks.

=== Result of Allocating Multiple Memory Blocks ===

The MemList created by AllocTaskMemEntry() contains MemEntry entries. MemEntrys are defined by a union statement, which allows one memory space to be defined in more than one way.

If AllocTaskMemEntry() returns a non-NULL value then all of the meu_Addr positions in the returned MemList will contain valid memory addresses meeting the requirements you have provided. To use this memory area, you would use code similar to the following:

<syntaxhighlight>
struct MemList *mlist = IExec->AllocTaskMemEntry(&ML);
APTR memory = NULL;

if ( mlist != NULL )
{
memory = mlist->ml_ME[0].me_Un.meu_Addr;
}
</syntaxhighlight>

=== Multiple Memory Blocks and Tasks ===

If you want to take advantage of Exec's automatic cleanup, use the MemList and AllocTaskMemEntry() facility to do your dynamic memory allocation.

In the Task control block structure, there is a list header named tc_MemEntry.

This is the list header that you initialize to include MemLists that your task has created by call(s) to AllocTaskMemEntry(). Here is a short program segment that handles task memory list header initialization only. It assumes that you have already run AllocTaskMemEntry() as shown in the simple AllocTaskMemEntry() example above.

<syntaxhighlight>
struct MemList *ml;

struct Task *tc = IExec->FindTask(0);

IExec->AddTail(tc->tc_MemEntry, ml);
</syntaxhighlight>

Assuming that you have only used the AllocTaskMemEntry() method (or AllocVecTags() and built your own custom MemList), the system now knows where to find the blocks of memory that your task has dynamically allocated. The RemTask() function automatically frees all memory found on tc_MemEntry.

{{Note|title=''CreateTask() Sets Up A MemList.''|text=The CreateTask() function, and other system task and process creation functions use a MemList in tc_MemEntry so that the Task structure and stack will be automatically deallocated when the Task is removed.}}

=== Summary of Multiple Memory Blocks Allocation Routines ===

These are routines for allocating and freeing multiple memory blocks with a single call.

This routine initializes memory from data and offset values in a table. Typically only assembly language programs benefit from using this routine. See the SDK for more details.

== Allocating Memory at an Absolute Address ==

For special advanced applications, AllocAbs() is provided. Using AllocAbs(), an application can allocate a memory block starting at a specified absolute memory address. If the memory is already allocated or if there is not enough memory available for the request, AllocAbs() returns a zero.

Be aware that an absolute memory address which happens to be available on one Amiga may not be available on a machine with a different configuration or different operating system revision, or even on the same machine at a different times. For example, a piece of memory that is available during expansion board configuration might not be available at earlier or later times. Here is an example call to AllocAbs():

<syntaxhighlight>
APTR absoluteptr = (APTR)IExec->AllocAbs(10000, 0x2F0000);
if (!(absoluteptr))
{ /* Couldn't get memory, act accordingly. */ }

/* After we're done using it, we call FreeMem() to free the memory block. */
IExec->FreeMem(absoluteptr, 10000);
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the Exec functions that handle memory management. See the SDK for details on each call.

{| class="wikitable"
! Memory Function
! Description
|-
| AllocMem()
| Allocate memory with specified attributes. '''This function is obsolete.'''
|-
| AllocAbs()
| Allocate memory at a specified location.
|-
| AllocTaskMemEntry()
| Allocate multiple memory blocks.
|-
| AllocVec()
| Allocate memory with specified attributes and keep track of the size. This function is obsolete.
|-
| AllocVecTags()
| Allocate memory with specified attributes defined by tags and keep track of the size. If an application needs to allocate some memory, it will usually use this function.
|-
| AvailMem()
| Return the amount of free memory, given certain conditions.
|-
| CopyMem()
| Copy memory block, which can be non-aligned and of arbitrary length.
|-
| CopyMemQuick()
| Copy aligned memory block.
|-
| FreeEntry()
| Free multiple memory blocks, allocated with AllocTaskMemEntry().
|-
| FreeMem()
| Free a memory block of specified size, allocated with AllocMem() or AllocAbs().
|-
| FreeVec()
| Free a memory block allocated with AllocVecTags() or AllocVec().
|-
| InitStruct()
| Initialize memory from a table.
|-
| LockMem()
| Lock the underlying pages given a memory block address and size.
|-
| TypeOfMem()
| Determine attributes of a specified memory address.
|-
| UnlockMem()
| Unlock the underlying pages given a memory block address and size.
|}

Exec Memory Allocation

2023-11-04T15:13:45Z

Ryan Dixon: /* Program Address Space */

== Exec Memory Allocation ==

Exec manages all of the free memory currently available in the system. Using a slab allocation system, Exec keeps track of memory and provides the functions to allocate and access it.

When an application needs some memory, it can either declare the memory statically within the program or it can ask Exec for some memory. When Exec receives a request for memory, it searches its free memory regions to find a suitably sized block that matches the size and attributes requested.

Prior to AmigaOS 4.0, the OS did not make use of the CPU's memory management unit and used memory "as-is". That is, if you have different memory expansions plugged into your system, the memory will be seen as chunks located somewhere in the 4 gigabyte address space. Since version 4.0, the MMU will be used to "map" memory pages from their physical location to a virtual address. There are multiple reasons why this is better than using the verbatim physical addresses - among other things it reduces the effect of "memory fragmentation" and simplifies the possibility to swap currently unused memory pages to persistent storage such as a hard disk.

The "downside" is that the virtual address of a memory block is almost never identical to the physical address. This isn't much of a downside, since an application will never really need to care about it. If an application allocates a block of memory of n bytes, it will get a pointer back that points to at least n continuous addresses as expected. The pages that "fill" this memory block may come from different physical locations scattered throughout the physical memory but a program will never noticed that. For all intent and purpose, the application sees a single continuous block of memory.

=== Program Address Space ===

It is important to remember that, just like in classic AmigaOS, a single address space is used for all programs. Sometimes the mention of an MMU can lead people to assume that each process on the Amiga will have its own personal, partitioned address space. The following two programs demonstrate that, even though they are separate processes, it is possible to read and write another's memory. The memory locations are the same virtual address and that virtual address maps onto the same physical address.

The following demonstrates how it is possible to read/write memory that is "owned" by a different process:

This program has a global variable. It prints out the virtual address of the global, waits for a keypress and then prints out the address again in case it has been externally updated:
<pre>
#include <stdlib.h>
#include <stdio.h>

volatile char x = 127;

/* Usage: a [VAL] */
int main(int argc, char *argv[])
{
if(argc==2)
x = (char)atoi(argv[1]);

printf("Virtual Address of `x': %p\n", (void*)&x);
printf("Dereferenced Value of `x': %d\n", x);
(void)getchar();
printf("Final Value of `x': %d\n", x);
return 0;
}
</pre>

This program reads in an address as an argument and reads the value at that location even though it does not "own" the memory. By adding an additional argument, this program can also write to that "foreign" address:
<pre>
#include <stdlib.h>
#include <stdio.h>

/* Usage: b ADDR [VAL_TO_WRITE] */
int main(int argc, char *argv[])
{
if(!(argc==2 || argc==3))
return 10;

volatile char *byte = (volatile char*)strtol(argv[1],NULL,16);
printf("Selected Virtual Address : %p\n",(void*)byte);
printf("Dereferencd Value of Address: %d\n",*byte);
if(argc==3)
{
printf("Writing Value `%d' to Address: %p\n",atoi(argv[2]),(void*)byte);
*byte=(char)atoi(argv[2]);
}

return 0;
}
</pre>

=== Slab allocation ===

[[File:SlabDiagram.jpg|right]]

The AmigaOS memory architecture is based on the "slab allocator" system or "object cache". In essence, the slab allocator only allocates objects of a single size, allocating these in larger batches ("slabs") from the low-level page allocator. These slabs are then divided up into buffers of the required size, and kept within a list in the slab allocator.

Allocating an object with the slab allocator becomes a process of simple node removal: the first node in the first slab containing free nodes is removed and returned for use. Since the slab allocator keeps free slabs or partially free slabs in a separate list from the full slabs, this operation can be carried out in constant time. Freeing memory is accomplished by returning the buffer to its cache, and adding it to its original slab's free list. Slabs that are completely free can be returned to the system's page pool (this operation is actually driven by demand, and timestamps are used to avoid unnecessary loading of data, or "thrashing"). External fragmentation is minimal, and internal fragmentation is controlled and guaranteed not to exceed a certain amount.

=== Object caching ===

The slab allocator can also be used to cache objects. In the real world a lot of memory allocation operations will be used to allocate the same object. The system has a number of data structures which are allocated frequently (semaphores, message ports and the like). Every time such structures are allocated, they must be initialised, and when they are deleted again, they must be cleaned up. It's likely, however, that such a structure will be needed again in the future, so that it can be kept in its initialised state and re-used later. This further reduces the load on the allocator routines, and thus improves system performance.

The object caches work on memory that has already been mapped into the virtual memory space.

=== More Advantages ===

Another advantage is the possibility to improve CPU cache usage. Usually, most objects have "hot spots", i.e. they have a few fields that are used often. Since most of the time a little memory is left unused in a slab (the object size might not be a multiple of the slab size), this additional memory can be used to "shift" the hot spots by a few bytes to optimise the memory structure, leading to better cache usage.

Finally, the system can be expanded to multiple CPUs with next to no overhead. On multi-CPU system, these expanded slab allocators scale almost linearly with the number of CPUs employed, making it the ideal choice for such systems.

The combination of object caching and keeping caches for different memory blocks (for AllocVec/FreeVec emulation) makes the memory management more efficient, faster, and generally more future-proof than the old free list approach used in AmigaOS 3.x and earlier.

See Wikipedia for more information on [http://en.wikipedia.org/wiki/Slab_allocation slab allocator systems].

=== Physical page allocation ===

Every memory location in a computer system has its own, unique address. That is, there is a byte location at address x where you can store and retrieve a single byte. This address is fixed; there is no way to change it without physically changing the hardware. Therefore, this address is called the “physical” address.

The physical address of a memory page is most often completely irrelevant to the application. The CPU will typically only see the virtual address. AmigaOS will take care of assigning virtual addresses to memory paging. This is often called “mapping” a page. Only in very special cases will the physical address be relevant. For example, device drivers that want to pass memory to a hardware device via DMA. Since the MMU is part of the CPU, any external hardware like an IDE controller will not see the virtual but only physical addresses.

A common operation in memory allocation is the assignment of virtual addresses to physical memory locations. Allocation of physical memory is usually done differently from virtual allocations, since it's necessary to free up only part of the allocation (when for example the pager kicks in).

The de-facto standard in allocation of physical pages is a method invented by Knuth, called [http://en.wikipedia.org/wiki/Buddy_memory_allocation the "buddy system"]. Basically every modern operating system uses it and AmigaOS is no exception.

Buddy systems are in essence size-segregated free lists. To allocate, the system searches for a free block of at least the size of the allocation. Then, if the block is too large, it's split into two even-sized blocks. These blocks are called "buddies". One block is returned to it's appropriate free list, and the other is considered further, maybe splitting it further until it's size matches that of the allocation.

In a buddy system, it's easy to determine whether the "buddy" is free or not, because it's address can simply be decided based on the address of the block to be freed.

=== Virtual address space allocation ===

Most CPUs come with a special unit that is called a "memory management unit" or "MMU" for short. The MMU's primary job is to rearrange the physical memory within the 4 gigabytes of address space in a way that is convenient for the operating system and/or applications. To do that effectively, it divides the memory into blocks (called "pages"). For every page the MMU has an entry in a table that specifies where the CPU should "see" this page, and what special attributes the page has. The address where the CPU "sees" this page is a 32 bit address as well, but since the memory is not really located there, we call that a "virtual" address.

AmigaOS uses a resource map allocator for allocating virtual address space. Basically this is a means of managing a set of resources (not necessarily memory). For performance reason, it uses several optimization techniques.

For one, all free resource blocks are held in space-segregated lists, i.e. there is a list for each power-of-two resource group. This makes allocations a lot faster by providing an upper and lower bound for a search. For example, if you want to allocate a block of 2^10 bytes, you can basically skip searching any block below 2^10 bytes in size simply because it won't fit. Similarly, you don't need to search for blocks that are larger than, say, twice the size of the block, since there might still be blocks of a size near to what we need. Size-segregated free lists help narrow down the search, making the search itself faster and the result better in terms of fragmentation.

In addition, the resource maps use object caches for accelerating "small" allocations. Most allocations are below a certain size. For example, the virtual addresses are always allocated in chunks of at least one "page" in memory (4096 bytes). So it's common to allocate blocks of one, two, four, or eight pages. The object caches provide an easy method for keeping these common sizes, making every allocation of these sizes an exact fit, further reducing fragmentation.

=== Page cache ===

A lot of the time spent in allocating memory was spent looking for the appropriate pages in memory. A 256 MB memory system has 65536 4KB pages. These pages have to be searched for from time to time. Originally, hash tables were used but it turned out that distributing 65536 page entries over a few hash buckets still produced lists of several thousand pages that had to be traversed to find a page. The hash table was replaced with a radix tree. These trees are rather broad, but shallow, making traversal very fast. In usual circumstances, the tree does not grow more than 4 to 5 levels in depth, making searching of a page a matter of maximum 4 to 5 compare operations.

=== Pager ===

AmigaOS has the possibility to swap out parts of memory to disk in order to free up more memory for other applications. This feature allows applications to use more memory than is actually physically installed in the system.

Paging is commonly referred to as "virtual memory" by users and sometimes even software developers. The fact AmigaOS uses virtual memory does not imply the use of the pager.

The system can be tuned to different strategies, either page out only on demand (for highly interactive tasks), or based on other needs (lots of free memory in core for disk caches etc.).

The optimized data structures allow the memory system to operate at a very high speed.

The time for a memory allocation is now in the order of a few microseconds. This is especially true for small allocation (below 8096 bytes). During system testing it was observed that by the time the system has booted up to Workbench, there have already been 40,000 allocations to the global memory pool below 2096 bytes.

== Memory Functions ==

Normally, an application uses the AllocVecTags() function to ask for memory:

<syntaxhighlight>
void *AllocVecTags(uint32 size, uint32 tag1, ...);
</syntaxhighlight>

The size argument is the amount of memory the application needs and the tag list specifies the type of memory and any special memory characteristics (described later). If AllocVecTags() is successful, it returns a pointer to a block of memory. The memory allocation will fail if the system cannot find a big enough block with the requested attributes. If AllocVecTags() fails, it returns NULL.

Because the system only keeps track of how much free memory is available and not how much is in use, it has no idea what memory has been allocated by any task. This means an application has to explicitly return, or deallocate, any memory it has allocated so the system can reuse it. If an application does not return a block of memory to the system, the system will not be able to reallocate that memory to some other task. That block of memory will be lost until the Amiga is reset. If you are using AllocVecTags() to allocate memory, a call to FreeVec() will return that memory to the system:

<syntaxhighlight>
void FreeVec(void *memoryBlock);
</syntaxhighlight>

Here memoryBlock is a pointer to the memory block the application is returning to the system. The size of the memory block is tracked internally by the system.

Unlike some compiler memory allocation functions, the Amiga system memory allocation functions return memory blocks that are at least longword aligned. This means that the allocated memory will always start on an address which is at least evenly divisible by four. This alignment makes the memory suitable for any system structures or buffers which require word or long word alignment, and also provides optimal alignment for stacks and memory copying.

=== Memory Types ===

There are three primary types of memory in AmigaOS which are summarized in the following table:

{| class="wikitable"
! Type
! Use
|-
| MEMF_PRIVATE
| This memory is private and only accessible within the context of the Task which allocated it. Private memory should always be preferred. Private memory is also swappable by default (i.e. not locked). This memory will not be visible to any other address space.
In a future version of AmigaOS, it is planned to have Task specific address spaces. This means each task could potentially address up to 4 GB of private memory each.
|-
| MEMF_SHARED
| The memory is shared and accessible by any Task in the system without restriction. This memory can be shared between all address spaces and will always appear at the same address in any address space. Shared memory is locked by default and thus is not swappable.
|-
| MEMF_EXECUTABLE
| The memory is used to store executable PowerPC code. This is used two-fold in AmigaOS. First, it allows the system to determine if a function pointer points to real native PowerPC code as opposed to 68k code which needs to be emulated. Second, it prevents common exploits that use stack overflows to execute malicious code. Executable memory is locked by default and thus is not swappable.
|}

=== Memory Attributes ===

Memory allocation on AmigaOS has traditionally been rather complicated. Over time, as new hardware models were released, more memory attribute flags were introduced.

All the various memory allocation functions and strategies have been consolidated and distilled into a single AllocVecTags() function call. Programmers are strongly encouraged to stop using any other function to allocate system memory. Using AllocVecTags() is the only way to guarantee future compatibility with more advanced AmigaOS features yet to come.

If an application does not specify any attributes when allocating memory, the system tries to satisfy the request with the fastest memory available on the system memory lists.

{{Note|title=Make Sure You Have Memory|text=Always check the result of any memory allocation to be sure the type and amount of memory requested is available. Failure to do so will lead to trying to use an non-valid pointer.}}

==== Using Tags ====

The AllocVecTags() function uses a tag list to define what attributes a block of memory must have. The currently supported tags are listed below.

{| class="wikitable"
! Tag (Default)
! Description
|-
| rowspan="4" | AVT_Type
(MEMF_PRIVATE)
|-
| MEMF_PRIVATE: Allocate from the task private heap. This memory will not be visible to any other address space.
|-
| MEMF_SHARED: Allocate from the system shared heap. This memory can be shared between all address spaces and will always appear at the same address in any address space. This memory is locked by default (see AVT_Lock tag below).
|-
| MEMF_EXECUTABLE: Allocate memory that is marked executable. This memory is locked by default (see AVT_Lock tag below).
|-
| AVT_Contiguous
(FALSE)
| Memory allocated with this property is allocated from a contiguous block of physical memory. This makes the memory suitable for DMA purposes when the DMA device does not support scatter/gather operation. For devices that do support scatter/gather use StartDMA() instead.
''Note:'' Physical pages can move at any time, be removed from memory due to paging or otherwise made unavailable unless the memory pages are locked (see LockMemory() function or AVT_Lock tag).
|-
| AVT_Lock
(TRUE or FALSE)
| After allocating memory, lock the associated pages in memory. This will prevent the pages from being moved, swapped out or otherwise being made unavailable. This is useful in conjunction with the AVT_Contiguous tag since it will ensure that the memory will stay contiguous after allocation.
This tag defaults to FALSE for MEMF_PRIVATE allocations and to TRUE for MEMF_SHARED or MEMF_EXECUTABLE.
|-
| AVT_Alignment
(16)
| Define an alignment constraint for the allocated memory block. The returned memory block will be aligned to the given size (in bytes). It's virtual address will be at least a multiple of the AVT_Alignment value.
''Note:'' Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_PhysicalAlignment
(16)
| Define an alignment constraint for the allocated memory block physical address. See AVT_Alignment for more information.
''Note:'' This functionality is mainly used for DMA drivers that require a specific alignment. Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_ClearWithValue
| Clear the newly allocated memory with the given byte value. If this tag is not given the memory block is not cleared.
|-
| AVT_Wait
(TRUE)
| Wait for the memory subsystem to be available. If TRUE, the calling task will be retired until the memory subsystem is available. This might cause a Forbid() to break. When FALSE and the memory subsystem is not currently available, the function will return immediately and the allocation will fail.
|-
| AVT_NoExpunge
(FALSE)
| If allocation fails because of unavailability, prevent invocation of low memory cleanup handlers. The default is FALSE which means that when memory is not available, cleanup handlers are invoked to try and satisfy the allocation.
|}

==== Using Flags ====

The use of memory flags was the only supported way to allocate memory prior to AmigaOS 4.0. It may be still useful to know more about this obsolete system for porting older applications. For more information about the memory flags system see [[Obsolete Exec Memory Allocation]].

=== Allocating System Memory ===

The following examples show how to allocate memory.

<syntaxhighlight>
APTR apointer = IExec->AllocVecTags(100, TAG_END);

if (apointer == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

AllocVecTags() returns the address of the first byte of a memory block that is at least 100 bytes in size or NULL if there is not that much free memory. Because there are no tags specified, private memory is assumed so this memory cannot be shared with any other tasks.

In addition to allocating a block of memory, this function keeps track of the size of the memory block, so your application doesn't have to remember it when it deallocates that memory block. The AllocVecTags() function allocates a little more memory to store the size of the memory allocation request.

{{Note|title=Make No Assumptions|It is not legal to peek the longword in front of the returned memory pointer to find out how big the block is. This has always been illegal regardless of what any other documentation may have stated to the contrary. Your application has access to the memory returned by AllocVecTags() and the only guarantee made is that the returned block has n bytes of continuous address space starting at the returned address. Anything outside this area is not to be touched.}}

<syntaxhighlight>
APTR anotherptr = IExec->AllocVecTags(1000,
AVT_Type, MEMF_SHARED,
AVT_Lock, FALSE,
AVT_ClearWithValue, 0,
TAG_END);

if (anotherptr == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocates shared memory which is accessible by any task in the system and clears the memory contents to zero. MEMF_SHARED memory is locked by default for compatibility with the obsolete MEMF_PUBLIC flag. This is by far the most common case when allocating shared memory.

<syntaxhighlight>
APTR lockedmem = IExec->AllocVecTags(3000,
AVT_Type, MEMF_SHARED,
TAG_END);

if (lockedmem == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocated shared memory which is accessible by any task in the system. MEMF_SHARED memory is locked by default so the underlying memory pages are not moveable and cannot be swapped out. Such memory could be used to share memory between a Process and an interrupt routine for example.

If the system free memory list does not contain enough contiguous memory bytes in an area matching your requirements, AllocVecTags() returns a zero. You ''must'' check for this condition.

<syntaxhighlight>
APTR yap = IExec->AllocVec(500, MEMF_CHIP);

if (yap == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The deprecated AllocVec() function is used in the example above because it is the only way to allocate MEMF_CHIP memory on a classic Amiga system.

=== Locking System Memory ===

The LockMem() function is used to explicitly lock a memory block. This function will make sure your memory block is not unmapped, swapped out or somehow made inaccessible. Use this function wisely. If there is no good reason to lock memory then do not do it. It will prevent the memory system from optimizing memory layout and may lead to poor performance.

<syntaxhighlight>
IExec->LockMem(mem, 1000);
</syntaxhighlight>

Before deallocating the memory is must be unlocked as well.

<syntaxhighlight>
IExec->UnLockMem(mem, 1000);
</syntaxhighlight>

{{Note|title=''Do not forget to UnlockMem()''|Failure to unlock memory will have adverse affects on the memory system. Locked memory pages cannot be moved so the system cannot optimize the layout of locked memory pages.}}

Be careful to always match the number of locks and the number of unlocks. If something else may have locked memory in the same page and an extraneous UnlockMem() decreases the lock reference counter to 0, that page can be paged out or moved. If that happens, for example, with data used in an interrupt handler or by the device driver which handles the swap partition the system will crash.

=== Freeing System Memory ===

The following examples free the memory chunks shown in the previous calls to AllocVecTags().

<syntaxhighlight>
IExec->FreeVec(apointer);

IExec->FreeVec(anotherptr);

IExec->FreeVec(lockedmem);

IExec->FreeVec(yap);
</syntaxhighlight>

A memory block allocated with AllocVecTags() or AllocVec() must be returned to the system pool with the FreeVec() function. This function uses the stored size in the allocation to free the memory block, so there is no need to specify the size of the memory block to free.

Any memory that is locked must be explicitly unlocked with UnlockMem() prior to freeing it. Failure to unlock memory will not cause any immediate problems but any pages which are locked cannot be moved or swapped out which can decrease system performance. Never unlock memory which has not been explicitly locked with LockMem() as it could lead to undefined behaviour.

FreeVec() returns no status. However, if you attempt to free a memory block in the middle of a chunk that the system believes is already free, you will cause a system crash. It is also illegal to free the same memory block twice and this will lead to a system crash.

{{Note|title=''Leave Memory Allocations Out Of Interrupt Code''|text=Do not allocate or deallocate system memory from within interrupt code. The [[Exec_Interrupts|Exec Interrupts]] section explains that an interrupt may occur at any time, even during a memory allocation process. As a result, system data structures may not be internally consistent at this time.}}

=== Memory may be Locked by Default ===

By default, the system memory allocation routines will allocate MEMF_SHARED and MEMF_EXECUTABLE memory and implicitly lock it. This memory must not be explicitly unlocked. Let the system handle the unlocking internally.

Here is the right way to allocate and free MEMF_SHARED memory:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->FreeVec(ptr);
</syntaxhighlight>

Here is the wrong way:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->UnlockMem(ptr, 10); // Doing this could lead to undefined system behaviour.
IExec->FreeVec(ptr);
</syntaxhighlight>

Unlocking memory not explicitly locked does not immediately cause any issues. However, in a future version of AmigaOS the memory pages may be handled differently than they are handled today. This could lead to incompatibilities with your applications and AmigaOS. The simple rule is that if you called LockMem() you must also call UnlockMem(). All other times you should not call UnlockMem().

{{Note|Memory locking is done at the page level. Even if a single byte of memory is locked in a page that entire page is locked. The programmer has no control over which pages may be used to satisfy a memory allocation.}}

{{Note|Shared and executable memory is locked implicitly for 68K backwards compatibility reasons. Use AVT_Lock (or equivalent) to ensure your shared and executable memory is not locked. MEMF_PRIVATE memory has no backwards compatibility issues and is always unlocked by default.}}

=== Memory Information Functions ===

The memory information routines AvailMem() and TypeOfMem() can provide the amount of memory available in the system, and the attributes of a particular block of memory.

==== Memory Requirements ====

The same attribute flags used in memory allocation routines are valid for the memory information routines. There is also an additional flag, MEMF_LARGEST, which can be used in the AvailMem() routine to find out what the largest available memory block of a particular type is. Specifying the MEMF_TOTAL flag will return the total amount of memory currently available.

==== Calling Memory Information Functions ====

The following example shows how to find out how much memory of a particular type is available.

<syntaxhighlight>
uint32 size = IExec->AvailMem(MEMF_CHIP | MEMF_LARGEST);
</syntaxhighlight>

AvailMem() returns the size of the largest chunk of available chip memory.

{{Note|title=''AvailMem() May Not Be Totally Accurate''|text=Because of multitasking, the return value from AvailMem() may be inaccurate by the time you receive it.}}

The following example shows how to determine the type of memory of a specified memory address.

<syntaxhighlight>
uint32 memtype = IExec->TypeOfMem((APTR)0x090000);
if ((memtype & MEMF_CHIP) == MEMF_CHIP) { /* ... It's chip memory ... */ }
</syntaxhighlight>

TypeOfMem() returns the attributes of the memory at a specific address. If it is passed an invalid memory address, TypeOfMem() returns NULL. This routine is normally used to determine if a particular chunk of memory is in chip memory.

=== Using Memory Copy Functions ===

For memory block copies, the CopyMem() and CopyMemQuick() functions can be used.

==== Copying System Memory ====

The following samples show how to use the copying routines.

<syntaxhighlight>
APTR source = IExec->AllocVecTags(1000, AVT_ClearWithValue, 0, TAG_END);
APTR target = IExec->AllocVecTags(1000, AVT_Type, MEMF_SHARED, TAG_END);
IExec->CopyMem(source, target, 1000);
</syntaxhighlight>

CopyMem() copies the specified number of bytes from the source data region to the target data region. The pointers to the regions can be aligned on arbitrary address boundaries. CopyMem() will attempt to copy the memory as efficiently as it can according to the alignment of the memory blocks, and the amount of data that it has to transfer. These functions are optimized for copying large blocks of memory which can result in unnecessary overhead if used to transfer very small blocks of memory.

CopyMemQuick() is now identical to CopyMem(). In previous versions of the operating system, CopyMemQuick() performed more optimized copying of the specified number of bytes from the source data region to the target data region. The source and target pointers must be longword aligned and the size (in bytes) must be divisible by four. There are no such restrictions starting with AmigaOS 4.0.

{{Note|title=''Not All Copies Are Supported''|text=Neither CopyMem() nor CopyMemQuick() supports copying between regions that overlap. For overlapping regions see MoveMem() in the [[Utility Library]].}}

=== System Memory Pools ===

A construct carried over from the AmigaOS 3.x Exec is the memory pool. The code handling memory pools uses an algorithm based on boundary tags and size-segregated memory lists. The speed gain is tremendous: even for the "dumb" case of just allocating 100000 blocks and freeing them again, the speed is ten times faster than the previous implementation. Due to the size-segregated free lists and the easy coalescing due to the boundary tags, real-life performance gain is even higher and would be between 10 and 20 times.

Two types of memory pools are available depending on the needs of the application:
* [[Exec_Item_Pools|Item Pools]] are built for speed and are used for allocating large numbers of items that are all the same size.
* Generic [[Exec_Memory_Pools|Memory Pools]] can handle allocations of different sizes at the expense of some speed.

=== Summary of System Controlled Memory Handling Routines ===

; AllocVecTags() and FreeVec()
: These are system-wide memory allocation and deallocation routines. They use a memory free-list owned and managed by the system.

; LockMem() and UnlockMem()
: These routines explicitly lock and unlock underlying memory pages.

; AvailMem()
: This routine returns the number of free bytes in a specified type of memory.

; TypeOfMem()
: This routine returns the memory attributes of a specified memory address.

; CopyMem() and CopyMemQuick()
: CopyMem() is a general purpose memory copy routine. CopyMemQuick() is an optimized version of CopyMemQuick(), but has restrictions on the size and alignment of the arguments.

== Allocating DMA Memory ==

Device drivers often use DMA to transfer data to and from the device. The StartDMA(), GetDMAList() and EndDMA() functions are used to create a scatter/gather list suitable for such DMA transfers.

The following conditions are guaranteed to be met when using these DMA functions:
* The memory region given is guaranteed to be mapped to physical memory.
* The mapping will not change as long as EndDMA() is not called.
* All cache entries in this region will be flushed out.

The example code below demonstrates how to perform a DMA write transfer:

<syntaxhighlight>
APTR addr;
uint32 size;

/* Tell the system to prepare for DMA */
uint32 arraySize = IExec->StartDMA(addr, size, 0);
if (arraySize > 0)
{
/* The memory area is prepared, allocate and retrieve the DMA list */
struct DMAEntry *DMAList = IExec->AllocSysObject(ASOT_DMAENTRY,
ASODMAE_NumEntries, arraySize,
TAG_END);

if (DMAList != NULL)
{
IExec->GetDMAList(addr, size, 0, DMAList);

/* Feed the DMA controller and do stuff */
...
/* Get rid of the DMAList's memory */

IExec->EndDMA(addr, size, endFlags);
IExec->FreeSysObject(ASOT_DMAENTRY, DMAList);
}
else
{
// Note We still call EndDMA() even though the actual
// transfer didn't happen.
IExec->EndDMA(addr, size, DMAF_NoModify);

IDOS->Printf("Can't allocate DMA list\n");
}
}
else
{
IDOS->Printf("Can't initiate DMA transfer\n");
}
</syntaxhighlight>

== Syncing and Memory Access ==

The PowerPC is a pure load/store architecture. That means, it will never operate on memory arguments like x86, to modify data, you have to load, modify and store.

All PowerPC/POWER cpus have a load/store queue, i.e. a queue where load and store operations are queued to reduce memory latency. If more than one store is made to the same long word (i.e. you write the first byte and then the second byte), then those stores are combined. As you can see, this will cause a problem for a chip register since both are written at the same time which is likely not what you want.

Similar for reading: A read might shortcut through the load/store queue and use a value that's already been read and is present in the load/store queue. Again, for chip registers, this will cause a problem because you might read an old value.

There are two instructions that deal with this: '''eieio''' (Ensure In-order Execution of I/O) and '''sync'''.

The eieio instruction simply inserts a "barrier" into the load/store queue. When combining ''stores'' the CPU never searches past this barrier for possible combines. This means that the sequence

# store to some address
# eieio
# store to some address + 1

will never be combined because of the eieio barrier between them.

The sync instruction will simply halt all execution and flush the load/store queue, executing and finishing all loads and stores.

As you can imagine, sync is MUCH MORE costly than eieio.

=== When to use eieio and sync ===

If you want to write, post fix your writes with an eieio instruction.

If you want to read, prefix your reads with a sync instruction.

This is also where the "GUARDED" memory flag comes in. GUARDED memory simply ensures program order of loads and stores, that is, it's an implicit eieio.

{{Note|Knowing when and how to use the '''eieio''' and '''sync''' instructions is somewhat vital for driver developers.}}

== Allocating Multiple Memory Blocks ==

Exec provides the routines AllocTaskMemEntry() and FreeEntry() to allocate multiple memory blocks in a single call.

AllocTaskMemEntry() accepts a data structure called a MemList, which contains the information about the size of the memory blocks to be allocated and the requirements, if any, that you have regarding the allocation.

The MemList structure is found in the include file <exec/memory.h> and is defined as follows:

<syntaxhighlight>
struct MemList
{
struct Node ml_Node;
UWORD ml_NumEntries; /* number of MemEntrys */
struct MemEntry ml_ME[1]; /* where the MemEntrys begin*/
};
</syntaxhighlight>

; ml_Node
: allows you to link together multiple MemLists. However, the node is ignored by the routines AllocTaskMemEntry() and FreeEntry().

; ml_NumEntries
: tells the system how many MemEntry sets are contained in this MemList. Notice that a MemList is a variable-length structure and can contain as many sets of entries as you wish.

The MemEntry structure looks like this:

<syntaxhighlight>
struct MemEntry
{
union {
ULONG meu_Reqs; /* the AllocMem requirements */
APTR meu_Addr; /* address of your memory */
} me_Un;
ULONG me_Length; /* the size of this request */
};
</syntaxhighlight>

=== Sample Code for Allocating Multiple Memory Blocks ===

Here's an example of showing how to use the AllocTaskMemEntry() with multiple blocks of memory.

<syntaxhighlight>
// alloctaskmementry.c - example of allocating several memory areas.
#include <exec/types.h>
#include <exec/memory.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct MemList *memlist; /* pointer to a MemList structure */

struct MemBlocks /* define a new structure because C cannot initialize unions */
{
struct MemList mn_head; /* one entry in the header */
struct MemEntry mn_body[3]; /* additional entries follow directly as */
} memblocks; /* part of the same data structure */

int main()
{
memblocks.mn_head.ml_NumEntries = 4; /* 4! Since the MemEntry starts at 1! */

/* Describe the first piece of memory we want. Because of our MemBlocks structure */
/* setup, we reference the first MemEntry differently when initializing it. */
memblocks.mn_head.ml_ME[0].me_Reqs = MEMF_CLEAR;
memblocks.mn_head.ml_ME[0].me_Length = 4000;

memblocks.mn_body[0].me_Reqs = MEMF_PRIVATE | MEMF_CLEAR;/* Describe the other pieces of */
memblocks.mn_body[0].me_Length = 100000; /* memory we want. Additional */
memblocks.mn_body[1].me_Reqs = MEMF_SHARED | MEMF_CLEAR; /* MemEntries are initialized this */
memblocks.mn_body[1].me_Length = 200000; /* way. If we wanted even more en- */
memblocks.mn_body[2].me_Reqs = MEMF_EXECUTABLE; /* tries, we would need to declare */
memblocks.mn_body[2].me_Length = 25000; /* a larger MemEntry array in our */
/* MemBlocks structure. */

memlist = (struct MemList *)IExec->AllocTaskMemEntry((struct MemList *)&memblocks);

if (memlist == NULL)
{
IDOS->Printf("AllocTaskMemEntry FAILED\n");
return RETURN_FAIL;
}

/* We got all memory we wanted. Use it and call FreeEntry() to free it */
IDOS->Printf("AllocTaskMemEntry succeeded - now freeing all allocated blocks\n");
IExec->FreeEntry(memlist);

return 0;
}
</syntaxhighlight>

AllocTaskMemEntry() returns a pointer to a new MemList of the same size as the MemList that you passed to it. For example, ROM code can provide a MemList containing the requirements of a task and create a RAM-resident copy of the list containing the addresses of the allocated entries. The pointer to the MemList is used as the argument for FreeEntry() to free the memory blocks.

=== Result of Allocating Multiple Memory Blocks ===

The MemList created by AllocTaskMemEntry() contains MemEntry entries. MemEntrys are defined by a union statement, which allows one memory space to be defined in more than one way.

If AllocTaskMemEntry() returns a non-NULL value then all of the meu_Addr positions in the returned MemList will contain valid memory addresses meeting the requirements you have provided. To use this memory area, you would use code similar to the following:

<syntaxhighlight>
struct MemList *mlist = IExec->AllocTaskMemEntry(&ML);
APTR memory = NULL;

if ( mlist != NULL )
{
memory = mlist->ml_ME[0].me_Un.meu_Addr;
}
</syntaxhighlight>

=== Multiple Memory Blocks and Tasks ===

If you want to take advantage of Exec's automatic cleanup, use the MemList and AllocTaskMemEntry() facility to do your dynamic memory allocation.

In the Task control block structure, there is a list header named tc_MemEntry.

This is the list header that you initialize to include MemLists that your task has created by call(s) to AllocTaskMemEntry(). Here is a short program segment that handles task memory list header initialization only. It assumes that you have already run AllocTaskMemEntry() as shown in the simple AllocTaskMemEntry() example above.

<syntaxhighlight>
struct MemList *ml;

struct Task *tc = IExec->FindTask(0);

IExec->AddTail(tc->tc_MemEntry, ml);
</syntaxhighlight>

Assuming that you have only used the AllocTaskMemEntry() method (or AllocVecTags() and built your own custom MemList), the system now knows where to find the blocks of memory that your task has dynamically allocated. The RemTask() function automatically frees all memory found on tc_MemEntry.

{{Note|title=''CreateTask() Sets Up A MemList.''|text=The CreateTask() function, and other system task and process creation functions use a MemList in tc_MemEntry so that the Task structure and stack will be automatically deallocated when the Task is removed.}}

=== Summary of Multiple Memory Blocks Allocation Routines ===

These are routines for allocating and freeing multiple memory blocks with a single call.

This routine initializes memory from data and offset values in a table. Typically only assembly language programs benefit from using this routine. See the SDK for more details.

== Allocating Memory at an Absolute Address ==

For special advanced applications, AllocAbs() is provided. Using AllocAbs(), an application can allocate a memory block starting at a specified absolute memory address. If the memory is already allocated or if there is not enough memory available for the request, AllocAbs() returns a zero.

Be aware that an absolute memory address which happens to be available on one Amiga may not be available on a machine with a different configuration or different operating system revision, or even on the same machine at a different times. For example, a piece of memory that is available during expansion board configuration might not be available at earlier or later times. Here is an example call to AllocAbs():

<syntaxhighlight>
APTR absoluteptr = (APTR)IExec->AllocAbs(10000, 0x2F0000);
if (!(absoluteptr))
{ /* Couldn't get memory, act accordingly. */ }

/* After we're done using it, we call FreeMem() to free the memory block. */
IExec->FreeMem(absoluteptr, 10000);
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the Exec functions that handle memory management. See the SDK for details on each call.

{| class="wikitable"
! Memory Function
! Description
|-
| AllocMem()
| Allocate memory with specified attributes. '''This function is obsolete.'''
|-
| AllocAbs()
| Allocate memory at a specified location.
|-
| AllocTaskMemEntry()
| Allocate multiple memory blocks.
|-
| AllocVec()
| Allocate memory with specified attributes and keep track of the size. This function is obsolete.
|-
| AllocVecTags()
| Allocate memory with specified attributes defined by tags and keep track of the size. If an application needs to allocate some memory, it will usually use this function.
|-
| AvailMem()
| Return the amount of free memory, given certain conditions.
|-
| CopyMem()
| Copy memory block, which can be non-aligned and of arbitrary length.
|-
| CopyMemQuick()
| Copy aligned memory block.
|-
| FreeEntry()
| Free multiple memory blocks, allocated with AllocTaskMemEntry().
|-
| FreeMem()
| Free a memory block of specified size, allocated with AllocMem() or AllocAbs().
|-
| FreeVec()
| Free a memory block allocated with AllocVecTags() or AllocVec().
|-
| InitStruct()
| Initialize memory from a table.
|-
| LockMem()
| Lock the underlying pages given a memory block address and size.
|-
| TypeOfMem()
| Determine attributes of a specified memory address.
|-
| UnlockMem()
| Unlock the underlying pages given a memory block address and size.
|}

Exec Memory Allocation

2023-11-04T15:13:09Z

Ryan Dixon:

== Exec Memory Allocation ==

Exec manages all of the free memory currently available in the system. Using a slab allocation system, Exec keeps track of memory and provides the functions to allocate and access it.

When an application needs some memory, it can either declare the memory statically within the program or it can ask Exec for some memory. When Exec receives a request for memory, it searches its free memory regions to find a suitably sized block that matches the size and attributes requested.

Prior to AmigaOS 4.0, the OS did not make use of the CPU's memory management unit and used memory "as-is". That is, if you have different memory expansions plugged into your system, the memory will be seen as chunks located somewhere in the 4 gigabyte address space. Since version 4.0, the MMU will be used to "map" memory pages from their physical location to a virtual address. There are multiple reasons why this is better than using the verbatim physical addresses - among other things it reduces the effect of "memory fragmentation" and simplifies the possibility to swap currently unused memory pages to persistent storage such as a hard disk.

The "downside" is that the virtual address of a memory block is almost never identical to the physical address. This isn't much of a downside, since an application will never really need to care about it. If an application allocates a block of memory of n bytes, it will get a pointer back that points to at least n continuous addresses as expected. The pages that "fill" this memory block may come from different physical locations scattered throughout the physical memory but a program will never noticed that. For all intent and purpose, the application sees a single continuous block of memory.

=== Program Address Space ===

It is important to remember that, just like in classic AmigaOS, a single address space is used for all programs. Sometimes the mention of an MMU can lead people to assume that each process on the Amiga will have its own personal, partitioned address space. The following two programs demonstrate that, even though they are separate processes, it is possible to read and write another's memory. The memory locations are the same virtual address and that virtual address maps onto the same physical address.

The following demonstrates how it is possible to read/write memory that is "owned" by a different process:

This program has a global variable. It prints out the virtual address of the global, waits for a keypress and then prints out the address again in case it has been externally updated:
<pre>
#include <stdlib.h>
#include <stdio.h>

volatile char x = 128;

/* Usage: a [VAL] */
int main(int argc, char *argv[])
{
if(argc==2)
x = (char)atoi(argv[1]);

printf("Virtual Address of `x': %p\n", (void*)&x);
printf("Dereferenced Value of `x': %d\n", x);
(void)getchar();
printf("Final Value of `x': %d\n", x);
return 0;
}
</pre>

This program reads in an address as an argument and reads the value at that location even though it does not "own" the memory. By adding an additional argument, this program can also write to that "foreign" address:
<pre>
#include <stdlib.h>
#include <stdio.h>

/* Usage: b ADDR [VAL_TO_WRITE] */
int main(int argc, char *argv[])
{
if(!(argc==2 || argc==3))
return 10;

volatile char *byte = (volatile char*)strtol(argv[1],NULL,16);
printf("Selected Virtual Address : %p\n",(void*)byte);
printf("Dereferencd Value of Address: %d\n",*byte);
if(argc==3)
{
printf("Writing Value `%d' to Address: %p\n",atoi(argv[2]),(void*)byte);
*byte=(char)atoi(argv[2]);
}

return 0;
}
</pre>

=== Slab allocation ===

[[File:SlabDiagram.jpg|right]]

The AmigaOS memory architecture is based on the "slab allocator" system or "object cache". In essence, the slab allocator only allocates objects of a single size, allocating these in larger batches ("slabs") from the low-level page allocator. These slabs are then divided up into buffers of the required size, and kept within a list in the slab allocator.

Allocating an object with the slab allocator becomes a process of simple node removal: the first node in the first slab containing free nodes is removed and returned for use. Since the slab allocator keeps free slabs or partially free slabs in a separate list from the full slabs, this operation can be carried out in constant time. Freeing memory is accomplished by returning the buffer to its cache, and adding it to its original slab's free list. Slabs that are completely free can be returned to the system's page pool (this operation is actually driven by demand, and timestamps are used to avoid unnecessary loading of data, or "thrashing"). External fragmentation is minimal, and internal fragmentation is controlled and guaranteed not to exceed a certain amount.

=== Object caching ===

The slab allocator can also be used to cache objects. In the real world a lot of memory allocation operations will be used to allocate the same object. The system has a number of data structures which are allocated frequently (semaphores, message ports and the like). Every time such structures are allocated, they must be initialised, and when they are deleted again, they must be cleaned up. It's likely, however, that such a structure will be needed again in the future, so that it can be kept in its initialised state and re-used later. This further reduces the load on the allocator routines, and thus improves system performance.

The object caches work on memory that has already been mapped into the virtual memory space.

=== More Advantages ===

Another advantage is the possibility to improve CPU cache usage. Usually, most objects have "hot spots", i.e. they have a few fields that are used often. Since most of the time a little memory is left unused in a slab (the object size might not be a multiple of the slab size), this additional memory can be used to "shift" the hot spots by a few bytes to optimise the memory structure, leading to better cache usage.

Finally, the system can be expanded to multiple CPUs with next to no overhead. On multi-CPU system, these expanded slab allocators scale almost linearly with the number of CPUs employed, making it the ideal choice for such systems.

The combination of object caching and keeping caches for different memory blocks (for AllocVec/FreeVec emulation) makes the memory management more efficient, faster, and generally more future-proof than the old free list approach used in AmigaOS 3.x and earlier.

See Wikipedia for more information on [http://en.wikipedia.org/wiki/Slab_allocation slab allocator systems].

=== Physical page allocation ===

Every memory location in a computer system has its own, unique address. That is, there is a byte location at address x where you can store and retrieve a single byte. This address is fixed; there is no way to change it without physically changing the hardware. Therefore, this address is called the “physical” address.

The physical address of a memory page is most often completely irrelevant to the application. The CPU will typically only see the virtual address. AmigaOS will take care of assigning virtual addresses to memory paging. This is often called “mapping” a page. Only in very special cases will the physical address be relevant. For example, device drivers that want to pass memory to a hardware device via DMA. Since the MMU is part of the CPU, any external hardware like an IDE controller will not see the virtual but only physical addresses.

A common operation in memory allocation is the assignment of virtual addresses to physical memory locations. Allocation of physical memory is usually done differently from virtual allocations, since it's necessary to free up only part of the allocation (when for example the pager kicks in).

The de-facto standard in allocation of physical pages is a method invented by Knuth, called [http://en.wikipedia.org/wiki/Buddy_memory_allocation the "buddy system"]. Basically every modern operating system uses it and AmigaOS is no exception.

Buddy systems are in essence size-segregated free lists. To allocate, the system searches for a free block of at least the size of the allocation. Then, if the block is too large, it's split into two even-sized blocks. These blocks are called "buddies". One block is returned to it's appropriate free list, and the other is considered further, maybe splitting it further until it's size matches that of the allocation.

In a buddy system, it's easy to determine whether the "buddy" is free or not, because it's address can simply be decided based on the address of the block to be freed.

=== Virtual address space allocation ===

Most CPUs come with a special unit that is called a "memory management unit" or "MMU" for short. The MMU's primary job is to rearrange the physical memory within the 4 gigabytes of address space in a way that is convenient for the operating system and/or applications. To do that effectively, it divides the memory into blocks (called "pages"). For every page the MMU has an entry in a table that specifies where the CPU should "see" this page, and what special attributes the page has. The address where the CPU "sees" this page is a 32 bit address as well, but since the memory is not really located there, we call that a "virtual" address.

AmigaOS uses a resource map allocator for allocating virtual address space. Basically this is a means of managing a set of resources (not necessarily memory). For performance reason, it uses several optimization techniques.

For one, all free resource blocks are held in space-segregated lists, i.e. there is a list for each power-of-two resource group. This makes allocations a lot faster by providing an upper and lower bound for a search. For example, if you want to allocate a block of 2^10 bytes, you can basically skip searching any block below 2^10 bytes in size simply because it won't fit. Similarly, you don't need to search for blocks that are larger than, say, twice the size of the block, since there might still be blocks of a size near to what we need. Size-segregated free lists help narrow down the search, making the search itself faster and the result better in terms of fragmentation.

In addition, the resource maps use object caches for accelerating "small" allocations. Most allocations are below a certain size. For example, the virtual addresses are always allocated in chunks of at least one "page" in memory (4096 bytes). So it's common to allocate blocks of one, two, four, or eight pages. The object caches provide an easy method for keeping these common sizes, making every allocation of these sizes an exact fit, further reducing fragmentation.

=== Page cache ===

A lot of the time spent in allocating memory was spent looking for the appropriate pages in memory. A 256 MB memory system has 65536 4KB pages. These pages have to be searched for from time to time. Originally, hash tables were used but it turned out that distributing 65536 page entries over a few hash buckets still produced lists of several thousand pages that had to be traversed to find a page. The hash table was replaced with a radix tree. These trees are rather broad, but shallow, making traversal very fast. In usual circumstances, the tree does not grow more than 4 to 5 levels in depth, making searching of a page a matter of maximum 4 to 5 compare operations.

=== Pager ===

AmigaOS has the possibility to swap out parts of memory to disk in order to free up more memory for other applications. This feature allows applications to use more memory than is actually physically installed in the system.

Paging is commonly referred to as "virtual memory" by users and sometimes even software developers. The fact AmigaOS uses virtual memory does not imply the use of the pager.

The system can be tuned to different strategies, either page out only on demand (for highly interactive tasks), or based on other needs (lots of free memory in core for disk caches etc.).

The optimized data structures allow the memory system to operate at a very high speed.

The time for a memory allocation is now in the order of a few microseconds. This is especially true for small allocation (below 8096 bytes). During system testing it was observed that by the time the system has booted up to Workbench, there have already been 40,000 allocations to the global memory pool below 2096 bytes.

== Memory Functions ==

Normally, an application uses the AllocVecTags() function to ask for memory:

<syntaxhighlight>
void *AllocVecTags(uint32 size, uint32 tag1, ...);
</syntaxhighlight>

The size argument is the amount of memory the application needs and the tag list specifies the type of memory and any special memory characteristics (described later). If AllocVecTags() is successful, it returns a pointer to a block of memory. The memory allocation will fail if the system cannot find a big enough block with the requested attributes. If AllocVecTags() fails, it returns NULL.

Because the system only keeps track of how much free memory is available and not how much is in use, it has no idea what memory has been allocated by any task. This means an application has to explicitly return, or deallocate, any memory it has allocated so the system can reuse it. If an application does not return a block of memory to the system, the system will not be able to reallocate that memory to some other task. That block of memory will be lost until the Amiga is reset. If you are using AllocVecTags() to allocate memory, a call to FreeVec() will return that memory to the system:

<syntaxhighlight>
void FreeVec(void *memoryBlock);
</syntaxhighlight>

Here memoryBlock is a pointer to the memory block the application is returning to the system. The size of the memory block is tracked internally by the system.

Unlike some compiler memory allocation functions, the Amiga system memory allocation functions return memory blocks that are at least longword aligned. This means that the allocated memory will always start on an address which is at least evenly divisible by four. This alignment makes the memory suitable for any system structures or buffers which require word or long word alignment, and also provides optimal alignment for stacks and memory copying.

=== Memory Types ===

There are three primary types of memory in AmigaOS which are summarized in the following table:

{| class="wikitable"
! Type
! Use
|-
| MEMF_PRIVATE
| This memory is private and only accessible within the context of the Task which allocated it. Private memory should always be preferred. Private memory is also swappable by default (i.e. not locked). This memory will not be visible to any other address space.
In a future version of AmigaOS, it is planned to have Task specific address spaces. This means each task could potentially address up to 4 GB of private memory each.
|-
| MEMF_SHARED
| The memory is shared and accessible by any Task in the system without restriction. This memory can be shared between all address spaces and will always appear at the same address in any address space. Shared memory is locked by default and thus is not swappable.
|-
| MEMF_EXECUTABLE
| The memory is used to store executable PowerPC code. This is used two-fold in AmigaOS. First, it allows the system to determine if a function pointer points to real native PowerPC code as opposed to 68k code which needs to be emulated. Second, it prevents common exploits that use stack overflows to execute malicious code. Executable memory is locked by default and thus is not swappable.
|}

=== Memory Attributes ===

Memory allocation on AmigaOS has traditionally been rather complicated. Over time, as new hardware models were released, more memory attribute flags were introduced.

All the various memory allocation functions and strategies have been consolidated and distilled into a single AllocVecTags() function call. Programmers are strongly encouraged to stop using any other function to allocate system memory. Using AllocVecTags() is the only way to guarantee future compatibility with more advanced AmigaOS features yet to come.

If an application does not specify any attributes when allocating memory, the system tries to satisfy the request with the fastest memory available on the system memory lists.

{{Note|title=Make Sure You Have Memory|text=Always check the result of any memory allocation to be sure the type and amount of memory requested is available. Failure to do so will lead to trying to use an non-valid pointer.}}

==== Using Tags ====

The AllocVecTags() function uses a tag list to define what attributes a block of memory must have. The currently supported tags are listed below.

{| class="wikitable"
! Tag (Default)
! Description
|-
| rowspan="4" | AVT_Type
(MEMF_PRIVATE)
|-
| MEMF_PRIVATE: Allocate from the task private heap. This memory will not be visible to any other address space.
|-
| MEMF_SHARED: Allocate from the system shared heap. This memory can be shared between all address spaces and will always appear at the same address in any address space. This memory is locked by default (see AVT_Lock tag below).
|-
| MEMF_EXECUTABLE: Allocate memory that is marked executable. This memory is locked by default (see AVT_Lock tag below).
|-
| AVT_Contiguous
(FALSE)
| Memory allocated with this property is allocated from a contiguous block of physical memory. This makes the memory suitable for DMA purposes when the DMA device does not support scatter/gather operation. For devices that do support scatter/gather use StartDMA() instead.
''Note:'' Physical pages can move at any time, be removed from memory due to paging or otherwise made unavailable unless the memory pages are locked (see LockMemory() function or AVT_Lock tag).
|-
| AVT_Lock
(TRUE or FALSE)
| After allocating memory, lock the associated pages in memory. This will prevent the pages from being moved, swapped out or otherwise being made unavailable. This is useful in conjunction with the AVT_Contiguous tag since it will ensure that the memory will stay contiguous after allocation.
This tag defaults to FALSE for MEMF_PRIVATE allocations and to TRUE for MEMF_SHARED or MEMF_EXECUTABLE.
|-
| AVT_Alignment
(16)
| Define an alignment constraint for the allocated memory block. The returned memory block will be aligned to the given size (in bytes). It's virtual address will be at least a multiple of the AVT_Alignment value.
''Note:'' Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_PhysicalAlignment
(16)
| Define an alignment constraint for the allocated memory block physical address. See AVT_Alignment for more information.
''Note:'' This functionality is mainly used for DMA drivers that require a specific alignment. Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_ClearWithValue
| Clear the newly allocated memory with the given byte value. If this tag is not given the memory block is not cleared.
|-
| AVT_Wait
(TRUE)
| Wait for the memory subsystem to be available. If TRUE, the calling task will be retired until the memory subsystem is available. This might cause a Forbid() to break. When FALSE and the memory subsystem is not currently available, the function will return immediately and the allocation will fail.
|-
| AVT_NoExpunge
(FALSE)
| If allocation fails because of unavailability, prevent invocation of low memory cleanup handlers. The default is FALSE which means that when memory is not available, cleanup handlers are invoked to try and satisfy the allocation.
|}

==== Using Flags ====

The use of memory flags was the only supported way to allocate memory prior to AmigaOS 4.0. It may be still useful to know more about this obsolete system for porting older applications. For more information about the memory flags system see [[Obsolete Exec Memory Allocation]].

=== Allocating System Memory ===

The following examples show how to allocate memory.

<syntaxhighlight>
APTR apointer = IExec->AllocVecTags(100, TAG_END);

if (apointer == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

AllocVecTags() returns the address of the first byte of a memory block that is at least 100 bytes in size or NULL if there is not that much free memory. Because there are no tags specified, private memory is assumed so this memory cannot be shared with any other tasks.

In addition to allocating a block of memory, this function keeps track of the size of the memory block, so your application doesn't have to remember it when it deallocates that memory block. The AllocVecTags() function allocates a little more memory to store the size of the memory allocation request.

{{Note|title=Make No Assumptions|It is not legal to peek the longword in front of the returned memory pointer to find out how big the block is. This has always been illegal regardless of what any other documentation may have stated to the contrary. Your application has access to the memory returned by AllocVecTags() and the only guarantee made is that the returned block has n bytes of continuous address space starting at the returned address. Anything outside this area is not to be touched.}}

<syntaxhighlight>
APTR anotherptr = IExec->AllocVecTags(1000,
AVT_Type, MEMF_SHARED,
AVT_Lock, FALSE,
AVT_ClearWithValue, 0,
TAG_END);

if (anotherptr == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocates shared memory which is accessible by any task in the system and clears the memory contents to zero. MEMF_SHARED memory is locked by default for compatibility with the obsolete MEMF_PUBLIC flag. This is by far the most common case when allocating shared memory.

<syntaxhighlight>
APTR lockedmem = IExec->AllocVecTags(3000,
AVT_Type, MEMF_SHARED,
TAG_END);

if (lockedmem == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocated shared memory which is accessible by any task in the system. MEMF_SHARED memory is locked by default so the underlying memory pages are not moveable and cannot be swapped out. Such memory could be used to share memory between a Process and an interrupt routine for example.

If the system free memory list does not contain enough contiguous memory bytes in an area matching your requirements, AllocVecTags() returns a zero. You ''must'' check for this condition.

<syntaxhighlight>
APTR yap = IExec->AllocVec(500, MEMF_CHIP);

if (yap == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The deprecated AllocVec() function is used in the example above because it is the only way to allocate MEMF_CHIP memory on a classic Amiga system.

=== Locking System Memory ===

The LockMem() function is used to explicitly lock a memory block. This function will make sure your memory block is not unmapped, swapped out or somehow made inaccessible. Use this function wisely. If there is no good reason to lock memory then do not do it. It will prevent the memory system from optimizing memory layout and may lead to poor performance.

<syntaxhighlight>
IExec->LockMem(mem, 1000);
</syntaxhighlight>

Before deallocating the memory is must be unlocked as well.

<syntaxhighlight>
IExec->UnLockMem(mem, 1000);
</syntaxhighlight>

{{Note|title=''Do not forget to UnlockMem()''|Failure to unlock memory will have adverse affects on the memory system. Locked memory pages cannot be moved so the system cannot optimize the layout of locked memory pages.}}

Be careful to always match the number of locks and the number of unlocks. If something else may have locked memory in the same page and an extraneous UnlockMem() decreases the lock reference counter to 0, that page can be paged out or moved. If that happens, for example, with data used in an interrupt handler or by the device driver which handles the swap partition the system will crash.

=== Freeing System Memory ===

The following examples free the memory chunks shown in the previous calls to AllocVecTags().

<syntaxhighlight>
IExec->FreeVec(apointer);

IExec->FreeVec(anotherptr);

IExec->FreeVec(lockedmem);

IExec->FreeVec(yap);
</syntaxhighlight>

A memory block allocated with AllocVecTags() or AllocVec() must be returned to the system pool with the FreeVec() function. This function uses the stored size in the allocation to free the memory block, so there is no need to specify the size of the memory block to free.

Any memory that is locked must be explicitly unlocked with UnlockMem() prior to freeing it. Failure to unlock memory will not cause any immediate problems but any pages which are locked cannot be moved or swapped out which can decrease system performance. Never unlock memory which has not been explicitly locked with LockMem() as it could lead to undefined behaviour.

FreeVec() returns no status. However, if you attempt to free a memory block in the middle of a chunk that the system believes is already free, you will cause a system crash. It is also illegal to free the same memory block twice and this will lead to a system crash.

{{Note|title=''Leave Memory Allocations Out Of Interrupt Code''|text=Do not allocate or deallocate system memory from within interrupt code. The [[Exec_Interrupts|Exec Interrupts]] section explains that an interrupt may occur at any time, even during a memory allocation process. As a result, system data structures may not be internally consistent at this time.}}

=== Memory may be Locked by Default ===

By default, the system memory allocation routines will allocate MEMF_SHARED and MEMF_EXECUTABLE memory and implicitly lock it. This memory must not be explicitly unlocked. Let the system handle the unlocking internally.

Here is the right way to allocate and free MEMF_SHARED memory:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->FreeVec(ptr);
</syntaxhighlight>

Here is the wrong way:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->UnlockMem(ptr, 10); // Doing this could lead to undefined system behaviour.
IExec->FreeVec(ptr);
</syntaxhighlight>

Unlocking memory not explicitly locked does not immediately cause any issues. However, in a future version of AmigaOS the memory pages may be handled differently than they are handled today. This could lead to incompatibilities with your applications and AmigaOS. The simple rule is that if you called LockMem() you must also call UnlockMem(). All other times you should not call UnlockMem().

{{Note|Memory locking is done at the page level. Even if a single byte of memory is locked in a page that entire page is locked. The programmer has no control over which pages may be used to satisfy a memory allocation.}}

{{Note|Shared and executable memory is locked implicitly for 68K backwards compatibility reasons. Use AVT_Lock (or equivalent) to ensure your shared and executable memory is not locked. MEMF_PRIVATE memory has no backwards compatibility issues and is always unlocked by default.}}

=== Memory Information Functions ===

The memory information routines AvailMem() and TypeOfMem() can provide the amount of memory available in the system, and the attributes of a particular block of memory.

==== Memory Requirements ====

The same attribute flags used in memory allocation routines are valid for the memory information routines. There is also an additional flag, MEMF_LARGEST, which can be used in the AvailMem() routine to find out what the largest available memory block of a particular type is. Specifying the MEMF_TOTAL flag will return the total amount of memory currently available.

==== Calling Memory Information Functions ====

The following example shows how to find out how much memory of a particular type is available.

<syntaxhighlight>
uint32 size = IExec->AvailMem(MEMF_CHIP | MEMF_LARGEST);
</syntaxhighlight>

AvailMem() returns the size of the largest chunk of available chip memory.

{{Note|title=''AvailMem() May Not Be Totally Accurate''|text=Because of multitasking, the return value from AvailMem() may be inaccurate by the time you receive it.}}

The following example shows how to determine the type of memory of a specified memory address.

<syntaxhighlight>
uint32 memtype = IExec->TypeOfMem((APTR)0x090000);
if ((memtype & MEMF_CHIP) == MEMF_CHIP) { /* ... It's chip memory ... */ }
</syntaxhighlight>

TypeOfMem() returns the attributes of the memory at a specific address. If it is passed an invalid memory address, TypeOfMem() returns NULL. This routine is normally used to determine if a particular chunk of memory is in chip memory.

=== Using Memory Copy Functions ===

For memory block copies, the CopyMem() and CopyMemQuick() functions can be used.

==== Copying System Memory ====

The following samples show how to use the copying routines.

<syntaxhighlight>
APTR source = IExec->AllocVecTags(1000, AVT_ClearWithValue, 0, TAG_END);
APTR target = IExec->AllocVecTags(1000, AVT_Type, MEMF_SHARED, TAG_END);
IExec->CopyMem(source, target, 1000);
</syntaxhighlight>

CopyMem() copies the specified number of bytes from the source data region to the target data region. The pointers to the regions can be aligned on arbitrary address boundaries. CopyMem() will attempt to copy the memory as efficiently as it can according to the alignment of the memory blocks, and the amount of data that it has to transfer. These functions are optimized for copying large blocks of memory which can result in unnecessary overhead if used to transfer very small blocks of memory.

CopyMemQuick() is now identical to CopyMem(). In previous versions of the operating system, CopyMemQuick() performed more optimized copying of the specified number of bytes from the source data region to the target data region. The source and target pointers must be longword aligned and the size (in bytes) must be divisible by four. There are no such restrictions starting with AmigaOS 4.0.

{{Note|title=''Not All Copies Are Supported''|text=Neither CopyMem() nor CopyMemQuick() supports copying between regions that overlap. For overlapping regions see MoveMem() in the [[Utility Library]].}}

=== System Memory Pools ===

A construct carried over from the AmigaOS 3.x Exec is the memory pool. The code handling memory pools uses an algorithm based on boundary tags and size-segregated memory lists. The speed gain is tremendous: even for the "dumb" case of just allocating 100000 blocks and freeing them again, the speed is ten times faster than the previous implementation. Due to the size-segregated free lists and the easy coalescing due to the boundary tags, real-life performance gain is even higher and would be between 10 and 20 times.

Two types of memory pools are available depending on the needs of the application:
* [[Exec_Item_Pools|Item Pools]] are built for speed and are used for allocating large numbers of items that are all the same size.
* Generic [[Exec_Memory_Pools|Memory Pools]] can handle allocations of different sizes at the expense of some speed.

=== Summary of System Controlled Memory Handling Routines ===

; AllocVecTags() and FreeVec()
: These are system-wide memory allocation and deallocation routines. They use a memory free-list owned and managed by the system.

; LockMem() and UnlockMem()
: These routines explicitly lock and unlock underlying memory pages.

; AvailMem()
: This routine returns the number of free bytes in a specified type of memory.

; TypeOfMem()
: This routine returns the memory attributes of a specified memory address.

; CopyMem() and CopyMemQuick()
: CopyMem() is a general purpose memory copy routine. CopyMemQuick() is an optimized version of CopyMemQuick(), but has restrictions on the size and alignment of the arguments.

== Allocating DMA Memory ==

Device drivers often use DMA to transfer data to and from the device. The StartDMA(), GetDMAList() and EndDMA() functions are used to create a scatter/gather list suitable for such DMA transfers.

The following conditions are guaranteed to be met when using these DMA functions:
* The memory region given is guaranteed to be mapped to physical memory.
* The mapping will not change as long as EndDMA() is not called.
* All cache entries in this region will be flushed out.

The example code below demonstrates how to perform a DMA write transfer:

<syntaxhighlight>
APTR addr;
uint32 size;

/* Tell the system to prepare for DMA */
uint32 arraySize = IExec->StartDMA(addr, size, 0);
if (arraySize > 0)
{
/* The memory area is prepared, allocate and retrieve the DMA list */
struct DMAEntry *DMAList = IExec->AllocSysObject(ASOT_DMAENTRY,
ASODMAE_NumEntries, arraySize,
TAG_END);

if (DMAList != NULL)
{
IExec->GetDMAList(addr, size, 0, DMAList);

/* Feed the DMA controller and do stuff */
...
/* Get rid of the DMAList's memory */

IExec->EndDMA(addr, size, endFlags);
IExec->FreeSysObject(ASOT_DMAENTRY, DMAList);
}
else
{
// Note We still call EndDMA() even though the actual
// transfer didn't happen.
IExec->EndDMA(addr, size, DMAF_NoModify);

IDOS->Printf("Can't allocate DMA list\n");
}
}
else
{
IDOS->Printf("Can't initiate DMA transfer\n");
}
</syntaxhighlight>

== Syncing and Memory Access ==

The PowerPC is a pure load/store architecture. That means, it will never operate on memory arguments like x86, to modify data, you have to load, modify and store.

All PowerPC/POWER cpus have a load/store queue, i.e. a queue where load and store operations are queued to reduce memory latency. If more than one store is made to the same long word (i.e. you write the first byte and then the second byte), then those stores are combined. As you can see, this will cause a problem for a chip register since both are written at the same time which is likely not what you want.

Similar for reading: A read might shortcut through the load/store queue and use a value that's already been read and is present in the load/store queue. Again, for chip registers, this will cause a problem because you might read an old value.

There are two instructions that deal with this: '''eieio''' (Ensure In-order Execution of I/O) and '''sync'''.

The eieio instruction simply inserts a "barrier" into the load/store queue. When combining ''stores'' the CPU never searches past this barrier for possible combines. This means that the sequence

# store to some address
# eieio
# store to some address + 1

will never be combined because of the eieio barrier between them.

The sync instruction will simply halt all execution and flush the load/store queue, executing and finishing all loads and stores.

As you can imagine, sync is MUCH MORE costly than eieio.

=== When to use eieio and sync ===

If you want to write, post fix your writes with an eieio instruction.

If you want to read, prefix your reads with a sync instruction.

This is also where the "GUARDED" memory flag comes in. GUARDED memory simply ensures program order of loads and stores, that is, it's an implicit eieio.

{{Note|Knowing when and how to use the '''eieio''' and '''sync''' instructions is somewhat vital for driver developers.}}

== Allocating Multiple Memory Blocks ==

Exec provides the routines AllocTaskMemEntry() and FreeEntry() to allocate multiple memory blocks in a single call.

AllocTaskMemEntry() accepts a data structure called a MemList, which contains the information about the size of the memory blocks to be allocated and the requirements, if any, that you have regarding the allocation.

The MemList structure is found in the include file <exec/memory.h> and is defined as follows:

<syntaxhighlight>
struct MemList
{
struct Node ml_Node;
UWORD ml_NumEntries; /* number of MemEntrys */
struct MemEntry ml_ME[1]; /* where the MemEntrys begin*/
};
</syntaxhighlight>

; ml_Node
: allows you to link together multiple MemLists. However, the node is ignored by the routines AllocTaskMemEntry() and FreeEntry().

; ml_NumEntries
: tells the system how many MemEntry sets are contained in this MemList. Notice that a MemList is a variable-length structure and can contain as many sets of entries as you wish.

The MemEntry structure looks like this:

<syntaxhighlight>
struct MemEntry
{
union {
ULONG meu_Reqs; /* the AllocMem requirements */
APTR meu_Addr; /* address of your memory */
} me_Un;
ULONG me_Length; /* the size of this request */
};
</syntaxhighlight>

=== Sample Code for Allocating Multiple Memory Blocks ===

Here's an example of showing how to use the AllocTaskMemEntry() with multiple blocks of memory.

<syntaxhighlight>
// alloctaskmementry.c - example of allocating several memory areas.
#include <exec/types.h>
#include <exec/memory.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct MemList *memlist; /* pointer to a MemList structure */

struct MemBlocks /* define a new structure because C cannot initialize unions */
{
struct MemList mn_head; /* one entry in the header */
struct MemEntry mn_body[3]; /* additional entries follow directly as */
} memblocks; /* part of the same data structure */

int main()
{
memblocks.mn_head.ml_NumEntries = 4; /* 4! Since the MemEntry starts at 1! */

/* Describe the first piece of memory we want. Because of our MemBlocks structure */
/* setup, we reference the first MemEntry differently when initializing it. */
memblocks.mn_head.ml_ME[0].me_Reqs = MEMF_CLEAR;
memblocks.mn_head.ml_ME[0].me_Length = 4000;

memblocks.mn_body[0].me_Reqs = MEMF_PRIVATE | MEMF_CLEAR;/* Describe the other pieces of */
memblocks.mn_body[0].me_Length = 100000; /* memory we want. Additional */
memblocks.mn_body[1].me_Reqs = MEMF_SHARED | MEMF_CLEAR; /* MemEntries are initialized this */
memblocks.mn_body[1].me_Length = 200000; /* way. If we wanted even more en- */
memblocks.mn_body[2].me_Reqs = MEMF_EXECUTABLE; /* tries, we would need to declare */
memblocks.mn_body[2].me_Length = 25000; /* a larger MemEntry array in our */
/* MemBlocks structure. */

memlist = (struct MemList *)IExec->AllocTaskMemEntry((struct MemList *)&memblocks);

if (memlist == NULL)
{
IDOS->Printf("AllocTaskMemEntry FAILED\n");
return RETURN_FAIL;
}

/* We got all memory we wanted. Use it and call FreeEntry() to free it */
IDOS->Printf("AllocTaskMemEntry succeeded - now freeing all allocated blocks\n");
IExec->FreeEntry(memlist);

return 0;
}
</syntaxhighlight>

AllocTaskMemEntry() returns a pointer to a new MemList of the same size as the MemList that you passed to it. For example, ROM code can provide a MemList containing the requirements of a task and create a RAM-resident copy of the list containing the addresses of the allocated entries. The pointer to the MemList is used as the argument for FreeEntry() to free the memory blocks.

=== Result of Allocating Multiple Memory Blocks ===

The MemList created by AllocTaskMemEntry() contains MemEntry entries. MemEntrys are defined by a union statement, which allows one memory space to be defined in more than one way.

If AllocTaskMemEntry() returns a non-NULL value then all of the meu_Addr positions in the returned MemList will contain valid memory addresses meeting the requirements you have provided. To use this memory area, you would use code similar to the following:

<syntaxhighlight>
struct MemList *mlist = IExec->AllocTaskMemEntry(&ML);
APTR memory = NULL;

if ( mlist != NULL )
{
memory = mlist->ml_ME[0].me_Un.meu_Addr;
}
</syntaxhighlight>

=== Multiple Memory Blocks and Tasks ===

If you want to take advantage of Exec's automatic cleanup, use the MemList and AllocTaskMemEntry() facility to do your dynamic memory allocation.

In the Task control block structure, there is a list header named tc_MemEntry.

This is the list header that you initialize to include MemLists that your task has created by call(s) to AllocTaskMemEntry(). Here is a short program segment that handles task memory list header initialization only. It assumes that you have already run AllocTaskMemEntry() as shown in the simple AllocTaskMemEntry() example above.

<syntaxhighlight>
struct MemList *ml;

struct Task *tc = IExec->FindTask(0);

IExec->AddTail(tc->tc_MemEntry, ml);
</syntaxhighlight>

Assuming that you have only used the AllocTaskMemEntry() method (or AllocVecTags() and built your own custom MemList), the system now knows where to find the blocks of memory that your task has dynamically allocated. The RemTask() function automatically frees all memory found on tc_MemEntry.

{{Note|title=''CreateTask() Sets Up A MemList.''|text=The CreateTask() function, and other system task and process creation functions use a MemList in tc_MemEntry so that the Task structure and stack will be automatically deallocated when the Task is removed.}}

=== Summary of Multiple Memory Blocks Allocation Routines ===

These are routines for allocating and freeing multiple memory blocks with a single call.

This routine initializes memory from data and offset values in a table. Typically only assembly language programs benefit from using this routine. See the SDK for more details.

== Allocating Memory at an Absolute Address ==

For special advanced applications, AllocAbs() is provided. Using AllocAbs(), an application can allocate a memory block starting at a specified absolute memory address. If the memory is already allocated or if there is not enough memory available for the request, AllocAbs() returns a zero.

Be aware that an absolute memory address which happens to be available on one Amiga may not be available on a machine with a different configuration or different operating system revision, or even on the same machine at a different times. For example, a piece of memory that is available during expansion board configuration might not be available at earlier or later times. Here is an example call to AllocAbs():

<syntaxhighlight>
APTR absoluteptr = (APTR)IExec->AllocAbs(10000, 0x2F0000);
if (!(absoluteptr))
{ /* Couldn't get memory, act accordingly. */ }

/* After we're done using it, we call FreeMem() to free the memory block. */
IExec->FreeMem(absoluteptr, 10000);
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the Exec functions that handle memory management. See the SDK for details on each call.

{| class="wikitable"
! Memory Function
! Description
|-
| AllocMem()
| Allocate memory with specified attributes. '''This function is obsolete.'''
|-
| AllocAbs()
| Allocate memory at a specified location.
|-
| AllocTaskMemEntry()
| Allocate multiple memory blocks.
|-
| AllocVec()
| Allocate memory with specified attributes and keep track of the size. This function is obsolete.
|-
| AllocVecTags()
| Allocate memory with specified attributes defined by tags and keep track of the size. If an application needs to allocate some memory, it will usually use this function.
|-
| AvailMem()
| Return the amount of free memory, given certain conditions.
|-
| CopyMem()
| Copy memory block, which can be non-aligned and of arbitrary length.
|-
| CopyMemQuick()
| Copy aligned memory block.
|-
| FreeEntry()
| Free multiple memory blocks, allocated with AllocTaskMemEntry().
|-
| FreeMem()
| Free a memory block of specified size, allocated with AllocMem() or AllocAbs().
|-
| FreeVec()
| Free a memory block allocated with AllocVecTags() or AllocVec().
|-
| InitStruct()
| Initialize memory from a table.
|-
| LockMem()
| Lock the underlying pages given a memory block address and size.
|-
| TypeOfMem()
| Determine attributes of a specified memory address.
|-
| UnlockMem()
| Unlock the underlying pages given a memory block address and size.
|}

Exec Memory Allocation

2023-11-04T15:08:59Z

Ryan Dixon: A mention on AmigaOS' Program Address Space

== Exec Memory Allocation ==

Exec manages all of the free memory currently available in the system. Using a slab allocation system, Exec keeps track of memory and provides the functions to allocate and access it.

When an application needs some memory, it can either declare the memory statically within the program or it can ask Exec for some memory. When Exec receives a request for memory, it searches its free memory regions to find a suitably sized block that matches the size and attributes requested.

Prior to AmigaOS 4.0, the OS did not make use of the CPU's memory management unit and used memory "as-is". That is, if you have different memory expansions plugged into your system, the memory will be seen as chunks located somewhere in the 4 gigabyte address space. Since version 4.0, the MMU will be used to "map" memory pages from their physical location to a virtual address. There are multiple reasons why this is better than using the verbatim physical addresses - among other things it reduces the effect of "memory fragmentation" and simplifies the possibility to swap currently unused memory pages to persistent storage such as a hard disk.

The "downside" is that the virtual address of a memory block is almost never identical to the physical address. This isn't much of a downside, since an application will never really need to care about it. If an application allocates a block of memory of n bytes, it will get a pointer back that points to at least n continuous addresses as expected. The pages that "fill" this memory block may come from different physical locations scattered throughout the physical memory but a program will never noticed that. For all intent and purpose, the application sees a single continuous block of memory.

=== Program Address Space ===

It is important to remember that, just like in classic AmigaOS, a single address space is used for all programs. Sometimes the mention of an MMU can lead people to assume that each process on the Amiga will have its own personal, partitioned address space. The following two programs demonstrate that, even though they are separate processes, it is possible to read and write another's memory. The memory locations are the same virtual address and that virtual address maps onto the same physical address.

The following demonstrates how it is possible to read/write memory that is "owned" by a different process:

This program has a global variable. It prints out the virtual address of the global, waits for a keypress and then prints out the address again in case it has been externally updated:
<pre>
#include <stdlib.h>
#include <stdio.h>

volatile char x = 255;

/* Usage: a [VAL] */
int main(int argc, char *argv[])
{
if(argc==2)
x = (char)atoi(argv[1]);

printf("Virtual Address of `x': %p\n", (void*)&x);
printf("Dereferenced Value of `x': %d\n", x);
(void)getchar();
printf("Final Value of `x': %d\n", x);
return 0;
}
</pre>

This program reads in an address as an argument and reads the value at that location even though it does not "own" the memory. By adding an additional argument, this program can also write to that "foreign" address:
<pre>
#include <stdlib.h>
#include <stdio.h>

/* Usage: b ADDR [VAL_TO_WRITE] */
int main(int argc, char *argv[])
{
if(!(argc==2 || argc==3))
return 10;

volatile char *byte = (volatile char*)strtol(argv[1],NULL,16);
printf("Selected Virtual Address : %p\n",(void*)byte);
printf("Dereferencd Value of Address: %d\n",*byte);
if(argc==3)
{
printf("Writing Value `%d' to Address: %p\n",atoi(argv[2]),(void*)byte);
*byte=(char)atoi(argv[2]);
}

return 0;
}
</pre>

=== Slab allocation ===

[[File:SlabDiagram.jpg|right]]

The AmigaOS memory architecture is based on the "slab allocator" system or "object cache". In essence, the slab allocator only allocates objects of a single size, allocating these in larger batches ("slabs") from the low-level page allocator. These slabs are then divided up into buffers of the required size, and kept within a list in the slab allocator.

Allocating an object with the slab allocator becomes a process of simple node removal: the first node in the first slab containing free nodes is removed and returned for use. Since the slab allocator keeps free slabs or partially free slabs in a separate list from the full slabs, this operation can be carried out in constant time. Freeing memory is accomplished by returning the buffer to its cache, and adding it to its original slab's free list. Slabs that are completely free can be returned to the system's page pool (this operation is actually driven by demand, and timestamps are used to avoid unnecessary loading of data, or "thrashing"). External fragmentation is minimal, and internal fragmentation is controlled and guaranteed not to exceed a certain amount.

=== Object caching ===

The slab allocator can also be used to cache objects. In the real world a lot of memory allocation operations will be used to allocate the same object. The system has a number of data structures which are allocated frequently (semaphores, message ports and the like). Every time such structures are allocated, they must be initialised, and when they are deleted again, they must be cleaned up. It's likely, however, that such a structure will be needed again in the future, so that it can be kept in its initialised state and re-used later. This further reduces the load on the allocator routines, and thus improves system performance.

The object caches work on memory that has already been mapped into the virtual memory space.

=== More Advantages ===

Another advantage is the possibility to improve CPU cache usage. Usually, most objects have "hot spots", i.e. they have a few fields that are used often. Since most of the time a little memory is left unused in a slab (the object size might not be a multiple of the slab size), this additional memory can be used to "shift" the hot spots by a few bytes to optimise the memory structure, leading to better cache usage.

Finally, the system can be expanded to multiple CPUs with next to no overhead. On multi-CPU system, these expanded slab allocators scale almost linearly with the number of CPUs employed, making it the ideal choice for such systems.

The combination of object caching and keeping caches for different memory blocks (for AllocVec/FreeVec emulation) makes the memory management more efficient, faster, and generally more future-proof than the old free list approach used in AmigaOS 3.x and earlier.

See Wikipedia for more information on [http://en.wikipedia.org/wiki/Slab_allocation slab allocator systems].

=== Physical page allocation ===

Every memory location in a computer system has its own, unique address. That is, there is a byte location at address x where you can store and retrieve a single byte. This address is fixed; there is no way to change it without physically changing the hardware. Therefore, this address is called the “physical” address.

The physical address of a memory page is most often completely irrelevant to the application. The CPU will typically only see the virtual address. AmigaOS will take care of assigning virtual addresses to memory paging. This is often called “mapping” a page. Only in very special cases will the physical address be relevant. For example, device drivers that want to pass memory to a hardware device via DMA. Since the MMU is part of the CPU, any external hardware like an IDE controller will not see the virtual but only physical addresses.

A common operation in memory allocation is the assignment of virtual addresses to physical memory locations. Allocation of physical memory is usually done differently from virtual allocations, since it's necessary to free up only part of the allocation (when for example the pager kicks in).

The de-facto standard in allocation of physical pages is a method invented by Knuth, called [http://en.wikipedia.org/wiki/Buddy_memory_allocation the "buddy system"]. Basically every modern operating system uses it and AmigaOS is no exception.

Buddy systems are in essence size-segregated free lists. To allocate, the system searches for a free block of at least the size of the allocation. Then, if the block is too large, it's split into two even-sized blocks. These blocks are called "buddies". One block is returned to it's appropriate free list, and the other is considered further, maybe splitting it further until it's size matches that of the allocation.

In a buddy system, it's easy to determine whether the "buddy" is free or not, because it's address can simply be decided based on the address of the block to be freed.

=== Virtual address space allocation ===

Most CPUs come with a special unit that is called a "memory management unit" or "MMU" for short. The MMU's primary job is to rearrange the physical memory within the 4 gigabytes of address space in a way that is convenient for the operating system and/or applications. To do that effectively, it divides the memory into blocks (called "pages"). For every page the MMU has an entry in a table that specifies where the CPU should "see" this page, and what special attributes the page has. The address where the CPU "sees" this page is a 32 bit address as well, but since the memory is not really located there, we call that a "virtual" address.

AmigaOS uses a resource map allocator for allocating virtual address space. Basically this is a means of managing a set of resources (not necessarily memory). For performance reason, it uses several optimization techniques.

For one, all free resource blocks are held in space-segregated lists, i.e. there is a list for each power-of-two resource group. This makes allocations a lot faster by providing an upper and lower bound for a search. For example, if you want to allocate a block of 2^10 bytes, you can basically skip searching any block below 2^10 bytes in size simply because it won't fit. Similarly, you don't need to search for blocks that are larger than, say, twice the size of the block, since there might still be blocks of a size near to what we need. Size-segregated free lists help narrow down the search, making the search itself faster and the result better in terms of fragmentation.

In addition, the resource maps use object caches for accelerating "small" allocations. Most allocations are below a certain size. For example, the virtual addresses are always allocated in chunks of at least one "page" in memory (4096 bytes). So it's common to allocate blocks of one, two, four, or eight pages. The object caches provide an easy method for keeping these common sizes, making every allocation of these sizes an exact fit, further reducing fragmentation.

=== Page cache ===

A lot of the time spent in allocating memory was spent looking for the appropriate pages in memory. A 256 MB memory system has 65536 4KB pages. These pages have to be searched for from time to time. Originally, hash tables were used but it turned out that distributing 65536 page entries over a few hash buckets still produced lists of several thousand pages that had to be traversed to find a page. The hash table was replaced with a radix tree. These trees are rather broad, but shallow, making traversal very fast. In usual circumstances, the tree does not grow more than 4 to 5 levels in depth, making searching of a page a matter of maximum 4 to 5 compare operations.

=== Pager ===

AmigaOS has the possibility to swap out parts of memory to disk in order to free up more memory for other applications. This feature allows applications to use more memory than is actually physically installed in the system.

Paging is commonly referred to as "virtual memory" by users and sometimes even software developers. The fact AmigaOS uses virtual memory does not imply the use of the pager.

The system can be tuned to different strategies, either page out only on demand (for highly interactive tasks), or based on other needs (lots of free memory in core for disk caches etc.).

The optimized data structures allow the memory system to operate at a very high speed.

The time for a memory allocation is now in the order of a few microseconds. This is especially true for small allocation (below 8096 bytes). During system testing it was observed that by the time the system has booted up to Workbench, there have already been 40,000 allocations to the global memory pool below 2096 bytes.

== Memory Functions ==

Normally, an application uses the AllocVecTags() function to ask for memory:

<syntaxhighlight>
void *AllocVecTags(uint32 size, uint32 tag1, ...);
</syntaxhighlight>

The size argument is the amount of memory the application needs and the tag list specifies the type of memory and any special memory characteristics (described later). If AllocVecTags() is successful, it returns a pointer to a block of memory. The memory allocation will fail if the system cannot find a big enough block with the requested attributes. If AllocVecTags() fails, it returns NULL.

Because the system only keeps track of how much free memory is available and not how much is in use, it has no idea what memory has been allocated by any task. This means an application has to explicitly return, or deallocate, any memory it has allocated so the system can reuse it. If an application does not return a block of memory to the system, the system will not be able to reallocate that memory to some other task. That block of memory will be lost until the Amiga is reset. If you are using AllocVecTags() to allocate memory, a call to FreeVec() will return that memory to the system:

<syntaxhighlight>
void FreeVec(void *memoryBlock);
</syntaxhighlight>

Here memoryBlock is a pointer to the memory block the application is returning to the system. The size of the memory block is tracked internally by the system.

Unlike some compiler memory allocation functions, the Amiga system memory allocation functions return memory blocks that are at least longword aligned. This means that the allocated memory will always start on an address which is at least evenly divisible by four. This alignment makes the memory suitable for any system structures or buffers which require word or long word alignment, and also provides optimal alignment for stacks and memory copying.

=== Memory Types ===

There are three primary types of memory in AmigaOS which are summarized in the following table:

{| class="wikitable"
! Type
! Use
|-
| MEMF_PRIVATE
| This memory is private and only accessible within the context of the Task which allocated it. Private memory should always be preferred. Private memory is also swappable by default (i.e. not locked). This memory will not be visible to any other address space.
In a future version of AmigaOS, it is planned to have Task specific address spaces. This means each task could potentially address up to 4 GB of private memory each.
|-
| MEMF_SHARED
| The memory is shared and accessible by any Task in the system without restriction. This memory can be shared between all address spaces and will always appear at the same address in any address space. Shared memory is locked by default and thus is not swappable.
|-
| MEMF_EXECUTABLE
| The memory is used to store executable PowerPC code. This is used two-fold in AmigaOS. First, it allows the system to determine if a function pointer points to real native PowerPC code as opposed to 68k code which needs to be emulated. Second, it prevents common exploits that use stack overflows to execute malicious code. Executable memory is locked by default and thus is not swappable.
|}

=== Memory Attributes ===

Memory allocation on AmigaOS has traditionally been rather complicated. Over time, as new hardware models were released, more memory attribute flags were introduced.

All the various memory allocation functions and strategies have been consolidated and distilled into a single AllocVecTags() function call. Programmers are strongly encouraged to stop using any other function to allocate system memory. Using AllocVecTags() is the only way to guarantee future compatibility with more advanced AmigaOS features yet to come.

If an application does not specify any attributes when allocating memory, the system tries to satisfy the request with the fastest memory available on the system memory lists.

{{Note|title=Make Sure You Have Memory|text=Always check the result of any memory allocation to be sure the type and amount of memory requested is available. Failure to do so will lead to trying to use an non-valid pointer.}}

==== Using Tags ====

The AllocVecTags() function uses a tag list to define what attributes a block of memory must have. The currently supported tags are listed below.

{| class="wikitable"
! Tag (Default)
! Description
|-
| rowspan="4" | AVT_Type
(MEMF_PRIVATE)
|-
| MEMF_PRIVATE: Allocate from the task private heap. This memory will not be visible to any other address space.
|-
| MEMF_SHARED: Allocate from the system shared heap. This memory can be shared between all address spaces and will always appear at the same address in any address space. This memory is locked by default (see AVT_Lock tag below).
|-
| MEMF_EXECUTABLE: Allocate memory that is marked executable. This memory is locked by default (see AVT_Lock tag below).
|-
| AVT_Contiguous
(FALSE)
| Memory allocated with this property is allocated from a contiguous block of physical memory. This makes the memory suitable for DMA purposes when the DMA device does not support scatter/gather operation. For devices that do support scatter/gather use StartDMA() instead.
''Note:'' Physical pages can move at any time, be removed from memory due to paging or otherwise made unavailable unless the memory pages are locked (see LockMemory() function or AVT_Lock tag).
|-
| AVT_Lock
(TRUE or FALSE)
| After allocating memory, lock the associated pages in memory. This will prevent the pages from being moved, swapped out or otherwise being made unavailable. This is useful in conjunction with the AVT_Contiguous tag since it will ensure that the memory will stay contiguous after allocation.
This tag defaults to FALSE for MEMF_PRIVATE allocations and to TRUE for MEMF_SHARED or MEMF_EXECUTABLE.
|-
| AVT_Alignment
(16)
| Define an alignment constraint for the allocated memory block. The returned memory block will be aligned to the given size (in bytes). It's virtual address will be at least a multiple of the AVT_Alignment value.
''Note:'' Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_PhysicalAlignment
(16)
| Define an alignment constraint for the allocated memory block physical address. See AVT_Alignment for more information.
''Note:'' This functionality is mainly used for DMA drivers that require a specific alignment. Alignment values must be powers of two. MEMF_EXECUTABLE memory is always aligned to the current page size.
|-
| AVT_ClearWithValue
| Clear the newly allocated memory with the given byte value. If this tag is not given the memory block is not cleared.
|-
| AVT_Wait
(TRUE)
| Wait for the memory subsystem to be available. If TRUE, the calling task will be retired until the memory subsystem is available. This might cause a Forbid() to break. When FALSE and the memory subsystem is not currently available, the function will return immediately and the allocation will fail.
|-
| AVT_NoExpunge
(FALSE)
| If allocation fails because of unavailability, prevent invocation of low memory cleanup handlers. The default is FALSE which means that when memory is not available, cleanup handlers are invoked to try and satisfy the allocation.
|}

==== Using Flags ====

The use of memory flags was the only supported way to allocate memory prior to AmigaOS 4.0. It may be still useful to know more about this obsolete system for porting older applications. For more information about the memory flags system see [[Obsolete Exec Memory Allocation]].

=== Allocating System Memory ===

The following examples show how to allocate memory.

<syntaxhighlight>
APTR apointer = IExec->AllocVecTags(100, TAG_END);

if (apointer == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

AllocVecTags() returns the address of the first byte of a memory block that is at least 100 bytes in size or NULL if there is not that much free memory. Because there are no tags specified, private memory is assumed so this memory cannot be shared with any other tasks.

In addition to allocating a block of memory, this function keeps track of the size of the memory block, so your application doesn't have to remember it when it deallocates that memory block. The AllocVecTags() function allocates a little more memory to store the size of the memory allocation request.

{{Note|title=Make No Assumptions|It is not legal to peek the longword in front of the returned memory pointer to find out how big the block is. This has always been illegal regardless of what any other documentation may have stated to the contrary. Your application has access to the memory returned by AllocVecTags() and the only guarantee made is that the returned block has n bytes of continuous address space starting at the returned address. Anything outside this area is not to be touched.}}

<syntaxhighlight>
APTR anotherptr = IExec->AllocVecTags(1000,
AVT_Type, MEMF_SHARED,
AVT_Lock, FALSE,
AVT_ClearWithValue, 0,
TAG_END);

if (anotherptr == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocates shared memory which is accessible by any task in the system and clears the memory contents to zero. MEMF_SHARED memory is locked by default for compatibility with the obsolete MEMF_PUBLIC flag. This is by far the most common case when allocating shared memory.

<syntaxhighlight>
APTR lockedmem = IExec->AllocVecTags(3000,
AVT_Type, MEMF_SHARED,
TAG_END);

if (lockedmem == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The example above allocated shared memory which is accessible by any task in the system. MEMF_SHARED memory is locked by default so the underlying memory pages are not moveable and cannot be swapped out. Such memory could be used to share memory between a Process and an interrupt routine for example.

If the system free memory list does not contain enough contiguous memory bytes in an area matching your requirements, AllocVecTags() returns a zero. You ''must'' check for this condition.

<syntaxhighlight>
APTR yap = IExec->AllocVec(500, MEMF_CHIP);

if (yap == NULL)
{ /* COULDN'T GET MEMORY, EXIT */ }
</syntaxhighlight>

The deprecated AllocVec() function is used in the example above because it is the only way to allocate MEMF_CHIP memory on a classic Amiga system.

=== Locking System Memory ===

The LockMem() function is used to explicitly lock a memory block. This function will make sure your memory block is not unmapped, swapped out or somehow made inaccessible. Use this function wisely. If there is no good reason to lock memory then do not do it. It will prevent the memory system from optimizing memory layout and may lead to poor performance.

<syntaxhighlight>
IExec->LockMem(mem, 1000);
</syntaxhighlight>

Before deallocating the memory is must be unlocked as well.

<syntaxhighlight>
IExec->UnLockMem(mem, 1000);
</syntaxhighlight>

{{Note|title=''Do not forget to UnlockMem()''|Failure to unlock memory will have adverse affects on the memory system. Locked memory pages cannot be moved so the system cannot optimize the layout of locked memory pages.}}

Be careful to always match the number of locks and the number of unlocks. If something else may have locked memory in the same page and an extraneous UnlockMem() decreases the lock reference counter to 0, that page can be paged out or moved. If that happens, for example, with data used in an interrupt handler or by the device driver which handles the swap partition the system will crash.

=== Freeing System Memory ===

The following examples free the memory chunks shown in the previous calls to AllocVecTags().

<syntaxhighlight>
IExec->FreeVec(apointer);

IExec->FreeVec(anotherptr);

IExec->FreeVec(lockedmem);

IExec->FreeVec(yap);
</syntaxhighlight>

A memory block allocated with AllocVecTags() or AllocVec() must be returned to the system pool with the FreeVec() function. This function uses the stored size in the allocation to free the memory block, so there is no need to specify the size of the memory block to free.

Any memory that is locked must be explicitly unlocked with UnlockMem() prior to freeing it. Failure to unlock memory will not cause any immediate problems but any pages which are locked cannot be moved or swapped out which can decrease system performance. Never unlock memory which has not been explicitly locked with LockMem() as it could lead to undefined behaviour.

FreeVec() returns no status. However, if you attempt to free a memory block in the middle of a chunk that the system believes is already free, you will cause a system crash. It is also illegal to free the same memory block twice and this will lead to a system crash.

{{Note|title=''Leave Memory Allocations Out Of Interrupt Code''|text=Do not allocate or deallocate system memory from within interrupt code. The [[Exec_Interrupts|Exec Interrupts]] section explains that an interrupt may occur at any time, even during a memory allocation process. As a result, system data structures may not be internally consistent at this time.}}

=== Memory may be Locked by Default ===

By default, the system memory allocation routines will allocate MEMF_SHARED and MEMF_EXECUTABLE memory and implicitly lock it. This memory must not be explicitly unlocked. Let the system handle the unlocking internally.

Here is the right way to allocate and free MEMF_SHARED memory:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->FreeVec(ptr);
</syntaxhighlight>

Here is the wrong way:
<syntaxhighlight>
APTR ptr = IExec->AllocVecTags(10,
AVT_Type, MEMF_SHARED,
TAG_END);
IExec->UnlockMem(ptr, 10); // Doing this could lead to undefined system behaviour.
IExec->FreeVec(ptr);
</syntaxhighlight>

Unlocking memory not explicitly locked does not immediately cause any issues. However, in a future version of AmigaOS the memory pages may be handled differently than they are handled today. This could lead to incompatibilities with your applications and AmigaOS. The simple rule is that if you called LockMem() you must also call UnlockMem(). All other times you should not call UnlockMem().

{{Note|Memory locking is done at the page level. Even if a single byte of memory is locked in a page that entire page is locked. The programmer has no control over which pages may be used to satisfy a memory allocation.}}

{{Note|Shared and executable memory is locked implicitly for 68K backwards compatibility reasons. Use AVT_Lock (or equivalent) to ensure your shared and executable memory is not locked. MEMF_PRIVATE memory has no backwards compatibility issues and is always unlocked by default.}}

=== Memory Information Functions ===

The memory information routines AvailMem() and TypeOfMem() can provide the amount of memory available in the system, and the attributes of a particular block of memory.

==== Memory Requirements ====

The same attribute flags used in memory allocation routines are valid for the memory information routines. There is also an additional flag, MEMF_LARGEST, which can be used in the AvailMem() routine to find out what the largest available memory block of a particular type is. Specifying the MEMF_TOTAL flag will return the total amount of memory currently available.

==== Calling Memory Information Functions ====

The following example shows how to find out how much memory of a particular type is available.

<syntaxhighlight>
uint32 size = IExec->AvailMem(MEMF_CHIP | MEMF_LARGEST);
</syntaxhighlight>

AvailMem() returns the size of the largest chunk of available chip memory.

{{Note|title=''AvailMem() May Not Be Totally Accurate''|text=Because of multitasking, the return value from AvailMem() may be inaccurate by the time you receive it.}}

The following example shows how to determine the type of memory of a specified memory address.

<syntaxhighlight>
uint32 memtype = IExec->TypeOfMem((APTR)0x090000);
if ((memtype & MEMF_CHIP) == MEMF_CHIP) { /* ... It's chip memory ... */ }
</syntaxhighlight>

TypeOfMem() returns the attributes of the memory at a specific address. If it is passed an invalid memory address, TypeOfMem() returns NULL. This routine is normally used to determine if a particular chunk of memory is in chip memory.

=== Using Memory Copy Functions ===

For memory block copies, the CopyMem() and CopyMemQuick() functions can be used.

==== Copying System Memory ====

The following samples show how to use the copying routines.

<syntaxhighlight>
APTR source = IExec->AllocVecTags(1000, AVT_ClearWithValue, 0, TAG_END);
APTR target = IExec->AllocVecTags(1000, AVT_Type, MEMF_SHARED, TAG_END);
IExec->CopyMem(source, target, 1000);
</syntaxhighlight>

CopyMem() copies the specified number of bytes from the source data region to the target data region. The pointers to the regions can be aligned on arbitrary address boundaries. CopyMem() will attempt to copy the memory as efficiently as it can according to the alignment of the memory blocks, and the amount of data that it has to transfer. These functions are optimized for copying large blocks of memory which can result in unnecessary overhead if used to transfer very small blocks of memory.

CopyMemQuick() is now identical to CopyMem(). In previous versions of the operating system, CopyMemQuick() performed more optimized copying of the specified number of bytes from the source data region to the target data region. The source and target pointers must be longword aligned and the size (in bytes) must be divisible by four. There are no such restrictions starting with AmigaOS 4.0.

{{Note|title=''Not All Copies Are Supported''|text=Neither CopyMem() nor CopyMemQuick() supports copying between regions that overlap. For overlapping regions see MoveMem() in the [[Utility Library]].}}

=== System Memory Pools ===

A construct carried over from the AmigaOS 3.x Exec is the memory pool. The code handling memory pools uses an algorithm based on boundary tags and size-segregated memory lists. The speed gain is tremendous: even for the "dumb" case of just allocating 100000 blocks and freeing them again, the speed is ten times faster than the previous implementation. Due to the size-segregated free lists and the easy coalescing due to the boundary tags, real-life performance gain is even higher and would be between 10 and 20 times.

Two types of memory pools are available depending on the needs of the application:
* [[Exec_Item_Pools|Item Pools]] are built for speed and are used for allocating large numbers of items that are all the same size.
* Generic [[Exec_Memory_Pools|Memory Pools]] can handle allocations of different sizes at the expense of some speed.

=== Summary of System Controlled Memory Handling Routines ===

; AllocVecTags() and FreeVec()
: These are system-wide memory allocation and deallocation routines. They use a memory free-list owned and managed by the system.

; LockMem() and UnlockMem()
: These routines explicitly lock and unlock underlying memory pages.

; AvailMem()
: This routine returns the number of free bytes in a specified type of memory.

; TypeOfMem()
: This routine returns the memory attributes of a specified memory address.

; CopyMem() and CopyMemQuick()
: CopyMem() is a general purpose memory copy routine. CopyMemQuick() is an optimized version of CopyMemQuick(), but has restrictions on the size and alignment of the arguments.

== Allocating DMA Memory ==

Device drivers often use DMA to transfer data to and from the device. The StartDMA(), GetDMAList() and EndDMA() functions are used to create a scatter/gather list suitable for such DMA transfers.

The following conditions are guaranteed to be met when using these DMA functions:
* The memory region given is guaranteed to be mapped to physical memory.
* The mapping will not change as long as EndDMA() is not called.
* All cache entries in this region will be flushed out.

The example code below demonstrates how to perform a DMA write transfer:

<syntaxhighlight>
APTR addr;
uint32 size;

/* Tell the system to prepare for DMA */
uint32 arraySize = IExec->StartDMA(addr, size, 0);
if (arraySize > 0)
{
/* The memory area is prepared, allocate and retrieve the DMA list */
struct DMAEntry *DMAList = IExec->AllocSysObject(ASOT_DMAENTRY,
ASODMAE_NumEntries, arraySize,
TAG_END);

if (DMAList != NULL)
{
IExec->GetDMAList(addr, size, 0, DMAList);

/* Feed the DMA controller and do stuff */
...
/* Get rid of the DMAList's memory */

IExec->EndDMA(addr, size, endFlags);
IExec->FreeSysObject(ASOT_DMAENTRY, DMAList);
}
else
{
// Note We still call EndDMA() even though the actual
// transfer didn't happen.
IExec->EndDMA(addr, size, DMAF_NoModify);

IDOS->Printf("Can't allocate DMA list\n");
}
}
else
{
IDOS->Printf("Can't initiate DMA transfer\n");
}
</syntaxhighlight>

== Syncing and Memory Access ==

The PowerPC is a pure load/store architecture. That means, it will never operate on memory arguments like x86, to modify data, you have to load, modify and store.

All PowerPC/POWER cpus have a load/store queue, i.e. a queue where load and store operations are queued to reduce memory latency. If more than one store is made to the same long word (i.e. you write the first byte and then the second byte), then those stores are combined. As you can see, this will cause a problem for a chip register since both are written at the same time which is likely not what you want.

Similar for reading: A read might shortcut through the load/store queue and use a value that's already been read and is present in the load/store queue. Again, for chip registers, this will cause a problem because you might read an old value.

There are two instructions that deal with this: '''eieio''' (Ensure In-order Execution of I/O) and '''sync'''.

The eieio instruction simply inserts a "barrier" into the load/store queue. When combining ''stores'' the CPU never searches past this barrier for possible combines. This means that the sequence

# store to some address
# eieio
# store to some address + 1

will never be combined because of the eieio barrier between them.

The sync instruction will simply halt all execution and flush the load/store queue, executing and finishing all loads and stores.

As you can imagine, sync is MUCH MORE costly than eieio.

=== When to use eieio and sync ===

If you want to write, post fix your writes with an eieio instruction.

If you want to read, prefix your reads with a sync instruction.

This is also where the "GUARDED" memory flag comes in. GUARDED memory simply ensures program order of loads and stores, that is, it's an implicit eieio.

{{Note|Knowing when and how to use the '''eieio''' and '''sync''' instructions is somewhat vital for driver developers.}}

== Allocating Multiple Memory Blocks ==

Exec provides the routines AllocTaskMemEntry() and FreeEntry() to allocate multiple memory blocks in a single call.

AllocTaskMemEntry() accepts a data structure called a MemList, which contains the information about the size of the memory blocks to be allocated and the requirements, if any, that you have regarding the allocation.

The MemList structure is found in the include file <exec/memory.h> and is defined as follows:

<syntaxhighlight>
struct MemList
{
struct Node ml_Node;
UWORD ml_NumEntries; /* number of MemEntrys */
struct MemEntry ml_ME[1]; /* where the MemEntrys begin*/
};
</syntaxhighlight>

; ml_Node
: allows you to link together multiple MemLists. However, the node is ignored by the routines AllocTaskMemEntry() and FreeEntry().

; ml_NumEntries
: tells the system how many MemEntry sets are contained in this MemList. Notice that a MemList is a variable-length structure and can contain as many sets of entries as you wish.

The MemEntry structure looks like this:

<syntaxhighlight>
struct MemEntry
{
union {
ULONG meu_Reqs; /* the AllocMem requirements */
APTR meu_Addr; /* address of your memory */
} me_Un;
ULONG me_Length; /* the size of this request */
};
</syntaxhighlight>

=== Sample Code for Allocating Multiple Memory Blocks ===

Here's an example of showing how to use the AllocTaskMemEntry() with multiple blocks of memory.

<syntaxhighlight>
// alloctaskmementry.c - example of allocating several memory areas.
#include <exec/types.h>
#include <exec/memory.h>
#include <proto/exec.h>
#include <proto/dos.h>

struct MemList *memlist; /* pointer to a MemList structure */

struct MemBlocks /* define a new structure because C cannot initialize unions */
{
struct MemList mn_head; /* one entry in the header */
struct MemEntry mn_body[3]; /* additional entries follow directly as */
} memblocks; /* part of the same data structure */

int main()
{
memblocks.mn_head.ml_NumEntries = 4; /* 4! Since the MemEntry starts at 1! */

/* Describe the first piece of memory we want. Because of our MemBlocks structure */
/* setup, we reference the first MemEntry differently when initializing it. */
memblocks.mn_head.ml_ME[0].me_Reqs = MEMF_CLEAR;
memblocks.mn_head.ml_ME[0].me_Length = 4000;

memblocks.mn_body[0].me_Reqs = MEMF_PRIVATE | MEMF_CLEAR;/* Describe the other pieces of */
memblocks.mn_body[0].me_Length = 100000; /* memory we want. Additional */
memblocks.mn_body[1].me_Reqs = MEMF_SHARED | MEMF_CLEAR; /* MemEntries are initialized this */
memblocks.mn_body[1].me_Length = 200000; /* way. If we wanted even more en- */
memblocks.mn_body[2].me_Reqs = MEMF_EXECUTABLE; /* tries, we would need to declare */
memblocks.mn_body[2].me_Length = 25000; /* a larger MemEntry array in our */
/* MemBlocks structure. */

memlist = (struct MemList *)IExec->AllocTaskMemEntry((struct MemList *)&memblocks);

if (memlist == NULL)
{
IDOS->Printf("AllocTaskMemEntry FAILED\n");
return RETURN_FAIL;
}

/* We got all memory we wanted. Use it and call FreeEntry() to free it */
IDOS->Printf("AllocTaskMemEntry succeeded - now freeing all allocated blocks\n");
IExec->FreeEntry(memlist);

return 0;
}
</syntaxhighlight>

AllocTaskMemEntry() returns a pointer to a new MemList of the same size as the MemList that you passed to it. For example, ROM code can provide a MemList containing the requirements of a task and create a RAM-resident copy of the list containing the addresses of the allocated entries. The pointer to the MemList is used as the argument for FreeEntry() to free the memory blocks.

=== Result of Allocating Multiple Memory Blocks ===

The MemList created by AllocTaskMemEntry() contains MemEntry entries. MemEntrys are defined by a union statement, which allows one memory space to be defined in more than one way.

If AllocTaskMemEntry() returns a non-NULL value then all of the meu_Addr positions in the returned MemList will contain valid memory addresses meeting the requirements you have provided. To use this memory area, you would use code similar to the following:

<syntaxhighlight>
struct MemList *mlist = IExec->AllocTaskMemEntry(&ML);
APTR memory = NULL;

if ( mlist != NULL )
{
memory = mlist->ml_ME[0].me_Un.meu_Addr;
}
</syntaxhighlight>

=== Multiple Memory Blocks and Tasks ===

If you want to take advantage of Exec's automatic cleanup, use the MemList and AllocTaskMemEntry() facility to do your dynamic memory allocation.

In the Task control block structure, there is a list header named tc_MemEntry.

This is the list header that you initialize to include MemLists that your task has created by call(s) to AllocTaskMemEntry(). Here is a short program segment that handles task memory list header initialization only. It assumes that you have already run AllocTaskMemEntry() as shown in the simple AllocTaskMemEntry() example above.

<syntaxhighlight>
struct MemList *ml;

struct Task *tc = IExec->FindTask(0);

IExec->AddTail(tc->tc_MemEntry, ml);
</syntaxhighlight>

Assuming that you have only used the AllocTaskMemEntry() method (or AllocVecTags() and built your own custom MemList), the system now knows where to find the blocks of memory that your task has dynamically allocated. The RemTask() function automatically frees all memory found on tc_MemEntry.

{{Note|title=''CreateTask() Sets Up A MemList.''|text=The CreateTask() function, and other system task and process creation functions use a MemList in tc_MemEntry so that the Task structure and stack will be automatically deallocated when the Task is removed.}}

=== Summary of Multiple Memory Blocks Allocation Routines ===

These are routines for allocating and freeing multiple memory blocks with a single call.

This routine initializes memory from data and offset values in a table. Typically only assembly language programs benefit from using this routine. See the SDK for more details.

== Allocating Memory at an Absolute Address ==

For special advanced applications, AllocAbs() is provided. Using AllocAbs(), an application can allocate a memory block starting at a specified absolute memory address. If the memory is already allocated or if there is not enough memory available for the request, AllocAbs() returns a zero.

Be aware that an absolute memory address which happens to be available on one Amiga may not be available on a machine with a different configuration or different operating system revision, or even on the same machine at a different times. For example, a piece of memory that is available during expansion board configuration might not be available at earlier or later times. Here is an example call to AllocAbs():

<syntaxhighlight>
APTR absoluteptr = (APTR)IExec->AllocAbs(10000, 0x2F0000);
if (!(absoluteptr))
{ /* Couldn't get memory, act accordingly. */ }

/* After we're done using it, we call FreeMem() to free the memory block. */
IExec->FreeMem(absoluteptr, 10000);
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the Exec functions that handle memory management. See the SDK for details on each call.

{| class="wikitable"
! Memory Function
! Description
|-
| AllocMem()
| Allocate memory with specified attributes. '''This function is obsolete.'''
|-
| AllocAbs()
| Allocate memory at a specified location.
|-
| AllocTaskMemEntry()
| Allocate multiple memory blocks.
|-
| AllocVec()
| Allocate memory with specified attributes and keep track of the size. This function is obsolete.
|-
| AllocVecTags()
| Allocate memory with specified attributes defined by tags and keep track of the size. If an application needs to allocate some memory, it will usually use this function.
|-
| AvailMem()
| Return the amount of free memory, given certain conditions.
|-
| CopyMem()
| Copy memory block, which can be non-aligned and of arbitrary length.
|-
| CopyMemQuick()
| Copy aligned memory block.
|-
| FreeEntry()
| Free multiple memory blocks, allocated with AllocTaskMemEntry().
|-
| FreeMem()
| Free a memory block of specified size, allocated with AllocMem() or AllocAbs().
|-
| FreeVec()
| Free a memory block allocated with AllocVecTags() or AllocVec().
|-
| InitStruct()
| Initialize memory from a table.
|-
| LockMem()
| Lock the underlying pages given a memory block address and size.
|-
| TypeOfMem()
| Determine attributes of a specified memory address.
|-
| UnlockMem()
| Unlock the underlying pages given a memory block address and size.
|}

Input Device

2023-11-04T01:13:56Z

Ryan Dixon:

[[Category:Devices|Input]]{{CodeReview}}
== Input Device ==

The input device is the central collection point for input events disseminated throughout the system. The best way to describe the input device is a manager of a stream with feeders. The input device itself and other modules such as the file system add events to the stream; so do input device “users”—programs or other devices that use parts of the stream or change it in some way. Feeders of the input device include the keyboard, timer and gameport devices. The keyboard, gameport, and timer devices are special cases in that the input device opens them and asks them for input. Users of the input device include Intuition and the console device.

== Input Device Commands and Functions ==

{| class="wikitable"
! Command
! Command Operation
|-
| CMD_FLUSH || Purge all active and queued requests for the input device.
|-
| CMD_RESET || Reset the input port to its initialized state. All active and queued I/O requests will be aborted. Restarts the device if it has been stopped.
|-
| CMD_START || Restart the currently active input (if any) and resume queued I/O requests.
|-
| CMD_STOP || Stop any currently active input and prevent queued I/O requests from starting.
|-
| IND_ADDEVENT || Propagate an input event to all handlers, updating event qualifiers.
|-
| IND_ADDHANDLER || Add an input-stream handler into the handler chain.
|-
| IND_ADDNOTIFY || Add a hook which will be invoked whenever a configuration option changes.
|-
| IND_GETHANDLERLIST || Obtain a pointer to the list of input handlers.
|-
| IND_GETKDEVICE || Query the name and unit number of the device keyboard input events are collected from.
|-
| IND_GETMDEVICE || Query the name and unit number of the device mouse input events are collected from.
|-
| IND_GETPERIOD || Get the key repeat period.
|-
| IND_GETTHRESH || Get the key repeat threshold.
|-
| IND_IMMEDIATEADDNOTIFY || Add a hook which will be invoked whenever a configuration option changes. The hook will be invoked on the current configuration first.
|-
| IND_REMHANDLER || Remove an input-stream handler from the handler chain.
|-
| IND_REMOVENOTIFY || Remove a hook previously installed with the IND_ADDNOTIFY command.
|-
| IND_SETKDEVICE || Choose the device to collect keyboard input events from.
|-
| IND_SETMDEVICE || Choose the device to collect mouse input events from.
|-
| IND_SETMPORT || Set the controller port to which the mouse is connected.
|-
| IND_SETMTRIG || Set conditions that must be met by a mouse before a pending read request will be satisfied.
|-
| IND_SETMTYPE || Set the type of device at the mouse port.
|-
| IND_SETPERIOD || Set the period at which a repeating key repeats.
|-
| IND_SETTHRESH || Set the repeating key hold-down time before repeat starts.
|-
| IND_WRITEEVENT || Propagate an input event stream to all devices.
|}

{| class="wikitable"
|+ Input Device Functions
| PeekQualifier() || Return the input device’s current qualifiers.
|}

== Device Interface ==

The input device operates like the other Amiga devices. To use it, you must first open the input device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

A number of structures are used by the input device to do its processing. Some are used to pass commands and data to the device, some are used to describe input events like mouse movements and key depressions, and one structure is used to describe the environment for input event handlers.

The I/O request used by the input device for most commands is IOStdReq.

<syntaxhighlight>
struct IOStdReq
{
struct Message io_Message; /* message reply port */
struct Device *io_Device; /* device node pointer */
struct Unit *io_Unit; /* unit */
UWORD io_Command; /* input device command */
UBYTE io_Flags; /* input device flags */
BYTE io_Error; /* error code */
ULONG io_Length; /* number of bytes to transfer */
APTR io_Data; /* pointer to data area */
};
</syntaxhighlight>

See the include file exec/io.h for the complete structure definition.

Two of the input device commands—IND_SETTHRESH and IND_SETPERIOD—require a time specification and ''must'' use a TimeRequest structure instead of an IOStdReq.

<syntaxhighlight>
struct TimeRequest
{
struct IORequest Request;
struct TimeVal Time;
};
</syntaxhighlight>

As you can see, the TimeRequest structure includes an IORequest structure. The io_Command field of the IORequest indicates the command to the input device and the TimeVal structure sets the time values. See the include file devices/timer.h for the complete structure definition.

{{Note|title=In Case You Feel Like Reinventing the Wheel...|text=You could define a “super-IORequest” structure for the input device which would combine the IOStdReq fields with the TimeVal structure of the TimeRequest structure.}}

=== Opening the Input Device ===

Three primary steps are required to open the input device:

* Create a message port using AllocSysObject() and ASOT_PORT type. Reply messages from the device must be directed to a message port.
* Create an extended I/O request structure of type IOStdReq or TimeRequest using AllocSysObject() and ASOT_IOREQUEST type. The I/O request created by the AllocSysObject() function will be used to pass commands and data to the input device.
* Open the Input device. Call OpenDevice(), passing the I/O request.

<syntaxhighlight>
struct MsgPort *InputMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (InputMP != NULL)
{
struct IOStdReq *InputIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, InputMP,
TAG_END);

if (ClipIO != NULL)
{
if (IExec->OpenDevice("input.device", 0, (struct IORequest *)InputIO, 0))
IDOS->Printf("input.device did not open\n");
</syntaxhighlight>

The above code will work for all the input device commands except for the ones which require a time specification. For those, the code would look like this:

<syntaxhighlight>
#include <devices/timer.h>

struct MsgPort *InputMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (InputMP != NULL)
{
struct TimeRequest *InputIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct TimeRequest),
ASOIOR_ReplyPort, InputMP,
TAG_END);

if (ClipIO != NULL)
{
if (IExec->OpenDevice("input.device", 0, (struct IORequest *)InputIO, 0))
IDOS->Printf("input.device did not open\n");
</syntaxhighlight>

=== Input Device Event Types ===

The input device is automatically opened by the console device when the system boots. When the input device is opened, a task named “input.device” is started. The input device task communicates directly with the keyboard device to obtain raw key events. It also communicates with the gameport device to obtain mouse button and mouse movement events and with the timer device to obtain time events. In addition to these events, you can add your own input events to the input device, to be fed to the handler chain (see below).

The keyboard device is accessible directly (see [[Keyboard_Device|Keyboard Device]]). However, once the input.device task has started, you should not read events from the keyboard device directly, since doing so will deprive the input device of the events and confuse key repeating.

The gameport device has two units. As you view the Amiga, looking at the gameport connectors, the left connector is assigned as the primary mouse input for Intuition and contributes gameport input events to the input event stream.

The right connector is handled by the other gameport unit and is currently unassigned. While the input device task is running, that task expects to read the input from the left connector. Direct use of the gameport device is covered in [[Gameport_Device|Gameport Device]].

The timer device is used to generate time events for the input device. It is also used to control key repeat rate and key repeat threshold. The timer device is a shared-access device and is described in [[Timer_Device|Timer Device]].

The device-specific commands are described below. First though, it may be helpful to consider the types of input events that the input device deals with. An input event is a data structure that describes the following:

* The class of the event — often describes the device that generated the event.
* The subclass of the event — space for more information if needed.
* The code — keycode if keyboard, button information if mouse, others.
* A qualifier such as “Alt key also down,”or “key repeat active”.
* A position field that contains a data address or a mouse position count.
* A time stamp, to determine the sequence in which the events occurred.
* A link-field by which input events are linked together.
* The class, subclass, code and qualifier of the previous down key.

The full definitions for each field can be found in the include file devices/inputevent.h. You can find more information about input events in [[Gameport_Device|Gameport Device]] and [[Console_Device|Console Device]].

The various types of input events are listed below.

{| class="wikitable"
|+ Input Device Event Types
| IECLASS_NULL || A NOP input event
|-
| IECLASS_RAWKEY || A raw keycode from the keyboard device
|-
| IECLASS_RAWMOUSE || The raw mouse report from the gameport device
|-
| IECLASS_EVENT || A private console event
|-
| IECLASS_POINTERPOS || A pointer position report
|-
| IECLASS_TIMER || A timer event
|-
| IECLASS_GADGETDOWN || Select button pressed down over a gadget (address in ie_EventAddress)
|-
| IECLASS_GADGETUP || Select button released over the same gadget (address in ie_EventAddress)
|-
| IECLASS_REQUESTER || Some requester activity has taken place.
|-
| IECLASS_MENULIST || This is a menu number transmission (menu number is in ie_Code)
|-
| IECLASS_CLOSEWINDOW || User has selected the active window’s Close Gadget
|-
| IECLASS_SIZEWINDOW || This window has a new size
|-
| IECLASS_REFRESHWINDOW || The window pointed to by ie_EventAddress needs to be refreshed
|-
| IECLASS_NEWPREFS || New preferences are available
|-
| IECLASS_DISKREMOVED || The disk has been removed
|-
| IECLASS_DISKINSERTED || The disk has been inserted
|-
| IECLASS_ACTIVEWINDOW || The window is about to be been made active
|-
| IECLASS_INACTIVEWINDOW || The window is about to be made inactive
|-
| IECLASS_NEWPOINTERPOS || Extended-function pointer position report
|-
| IECLASS_MENUHELP || Help key report during Menu session
|-
| IECLASS_CHANGEWINDOW || The Window has been modified with move, size, zoom, or change
|}

There is a difference between simply receiving an input event from a device and actually becoming a handler of an input event stream. A handler is a routine that is passed an input event list. It is up to the handler to decide if it can process the input events. If the handler does not recognize an event, it leaves it undisturbed in the event list.

{{Note|title=It All Flows Downhill|text=Handlers can themselves generate new linked lists of events which can be passed down to lower priority handlers.}}

The InputEvent structure is used by the input device to describe an input event such as a keypress or a mouse movement.

<syntaxhighlight>
struct InputEvent
{
struct InputEvent *ie_NextEvent; /* the chronologically next event */
UBYTE ie_Class; /* the input event class */
UBYTE ie_SubClass; /* optional subclass of the class */
UWORD ie_Code; /* the input event code */
UWORD ie_Qualifier; /* qualifiers in effect for the event*/
union
{
struct
{
WORD ie_x; /* the pointer position for the event*/
WORD ie_y;
} ie_xy;
APTR ie_addr; /* the event address */
struct
{
UBYTE ie_prev1DownCode; /* previous down keys for dead */
UBYTE ie_prev1DownQual; /* key translation: the ie_Code */
UBYTE ie_prev2DownCode; /* & low byte of ie_Qualifier for */
UBYTE ie_prev2DownQual; /* last & second last down keys */
} ie_dead;
} ie_position;
struct timeval ie_TimeStamp; /* the system tick at the event */
};
</syntaxhighlight>

The IEPointerPixel and IEPointerTablet structures are used to set the mouse position with the IECLASS_NEWPOINTERPOS input event class.

<syntaxhighlight>
struct IEPointerPixel
{
struct Screen *iepp_Screen; /* pointer to an open screen */
struct
{ /* pixel coordinates in iepp_Screen */
WORD X;
WORD Y;
} iepp_Position;
};

struct IEPointerTablet
{
struct
{
UWORD X;
UWORD Y;
} iept_Range; /* 0 is min, these are max */
struct
{
UWORD X;
UWORD Y;
} iept_Value; /* between 0 and iept_Range */

WORD iept_Pressure; /* -128 to 127 (unused, set to 0) */
};
</syntaxhighlight>

See the include file devices/inputevent.h for the complete structure definitions.

For input device handler installation, the Interrupt structure is used.

<syntaxhighlight>
struct Interrupt
{
struct Node is_Node;
APTR is_Data; /* server data segment */
VOID (*is_Code)(); /* server code entry */
};
</syntaxhighlight>

See the include file exec/interrupts.h for the complete structure definition.

=== Closing the Input Device ===

Each OpenDevice() must eventually be matched by a call to CloseDevice(). All I/O requests must be complete before CloseDevice(). If any requests are still pending, abort them with AbortIO():

<syntaxhighlight>
if (!(IExec->CheckIO(InputIO)))
{
IExec->AbortIO(InputIO); /* Ask device to abort request, if pending */
}
IExec->WaitIO(InputIO); /* Wait for abort, then clean up */
IExec->CloseDevice((struct IORequest *)InputIO);
</syntaxhighlight>

== Using the Mouse Port With the Input Device ==

To get mouse port information you must first set the current mouse port by passing an IOStdReq to the device with IND_SETMPORT set in io_Command and a pointer to a byte set in io_Data. If the byte is set to 0 the left controller port will be used as the current mouse port; if it is set to 1, the right controller port will be used.

<syntaxhighlight>
int8 port = 1; /* set mouse port to right controller */

InputIO->io_Data = &port;
InputIO->io_Flags = IOF_QUICK;
InputIO->io_Length = 1;
InputIO->io_Command = IND_SETMPORT;
IExec->BeginIO((struct IORequest *)InputIO);
if (InputIO->io_Error)
IDOS->Printf("\nSETMPORT failed %ld\n", InputIO->io_Error);
</syntaxhighlight>

{{Note|title=Put That Back!|text=The default mouse port is the left controller. Don’t forget to set the mouse port back to the left controller before exiting if you change it to the right controller during your application.}}

=== Setting the Conditions for a Mouse Port Report ===

You set the conditions for a mouse port report by passing an IOStdReq to the device with IND_SETMTRIG set in io_Command, the address of a GamePortTrigger structure set in io_Data and the length of the structure set in io_Length.

<syntaxhighlight>
struct GamePortTrigger InputTR;

InputIO->io_Data = (APTR)InputTR; /* set trigger conditions */
InputIO->io_Command = IND_SETMTRIG; /* from InputTR */
InputIO->io_Length = sizeof(struct GamePortTrigger);
IExec->DoIO(InputIO);
</syntaxhighlight>

The information needed for mouse port report setting is contained in a GamePortTrigger data structure which is defined in the include file devices/gameport.h.

<syntaxhighlight>
struct GamePortTrigger
{
UWORD gpt_Keys; /* key transition triggers */
UWORD gpt_Timeout; /* time trigger (vertical blank units) */
UWORD gpt_XDelta; /* X distance trigger */
UWORD gpt_YDelta; /* Y distance trigger */
};
</syntaxhighlight>

See [[Gameport Device]] for a full description of setting mouse port trigger conditions.

== Adding an Input Handler ==

You add an input-stream handler to the input chain by passing an IOStdReq to the device with IND_ADDHANDLER set in io_Command and a pointer to an Interrupt structure set in io_Data.

<syntaxhighlight>
struct Interrupt *InputHandler;
struct IOStdReq *InputIO

InputHandler->is_Code = ButtonSwap; /* Address of code */
InputHandler->is_Data = NULL; /* User Value passed in A1 */
InputHandler->is_Node.ln_Pri = 100; /* Priority in food chain */
InputHandler->is_Node.ln_Name = NameString; /* Name of handler */

InputIO->io_Data = (APTR)inputHandler; /* Point to the structure */
InputIO->io_Command = IND_ADDHANDLER; /* Set command ... */
IExec->DoIO((struct IORequest *)InputIO); /* DoIO( ) the command */
</syntaxhighlight>

Intuition is one of the input device handlers and normally distributes most of the input events.

Intuition inserts itself at priority position 50. The console device sits at priority position 0. You can choose the position in the chain at which your handler will be inserted by setting the priority field in the list-node part of the interrupt data structure you pass to this routine.

{{Note|title=Speed Saves|text=''Any'' processing time expended by a handler subtracts from the time available before the next event happens. Therefore, handlers for the input stream ''must'' be fast.}}

=== Rules for Input Device Handlers ===

The following rules should be followed when you are designing an input handler:

* If an input handler is capable of processing a specific kind of an input event and that event has no links (ie_NextEvent = 0), the handler can end the handler chain by returning a NULL (0) value.

* If there are multiple events linked together, the handler is free to unlink an event from the input event chain, thereby passing a shorter list of events to subsequent handlers. The starting address of the modified list is the return value.

* If a handler wishes to add new events to the chain that it passes to a lower-priority handler, it may initialize memory to contain the new event or event chain. The handler, when it again gets control on the next round of event handling, should assume nothing about the current contents of the memory blocks attached to the event chain. Lower priority handlers may have modified the memory as they handled their part of the event. The handler that allocates the memory for this purpose should keep track of the starting address and the size of this memory chunk so that the memory can be returned to the free memory list when it is no longer needed.

Your handler routine should be structured similar to the following pseudo-language statement:

<syntaxhighlight>
newEventChain = yourHandlerCode(oldEventChain, yourHandlerData);
</syntaxhighlight>

where:

; yourHandlerCode
: is the entry point to your routine.
; oldEventChain
: is the starting address for the current chain of input events.
; yourHandlerData
: is a user-definable value, usually a pointer to some data structure your handler requires.
; newEventChain
: is the starting address of an event chain which you are passing to the next handler, if any.

When your handler code is called, the event chain and the handler data is passed in. When your code returns, it should return the pointer to the event chain. If all of the events were removed by the routine, return NULL. A NULL (0) value terminates the handling thus freeing more CPU resources.

Memory that you use to describe a new input event that you have added to the event chain is available for reuse or deallocation when the handler is called again or after the IND_REMHANDLER command for the handler is complete. There is no guarantee that any field in the event is unchanged since a handler may change any field of an event that comes through the food chain.

Because IND_ADDHANDLER installs a handler in any position in the handler chain, it can, for example, ignore specific types of input events as well as act upon and modify existing streams of input. It can even create new input events for Intuition or other programs to interpret.

=== Removing an Input Handler ===

You remove a handler from the handler chain by passing an IOStdReq to the device IND_REMHANDLER set in io_Command and a pointer to the Interrupt structure used to add the handler.

<syntaxhighlight>
struct Interrupt *InputHandler;
struct IOStdReq *InputIO;

InputIO->io_Data = (APTR)InputHandler; /* Which handler to REM */
InputIO->io_Command = IND_REMHANDLER; /* The REM command */
IExec->DoIO((struct IORequest *)InputIO); /* Send the command */
</syntaxhighlight>

== Writing Events to the Input Device Stream ==

Typically, input events are internally generated by the timer device, keyboard device, and input device.

An application can also generate an input event by setting the appropriate fields for the event in an InputEvent structure and sending it to the input device. It will then be treated as any other event and passed through to the input handler chain. However, I/O requests for IND_WRITEVENT cannot be made from interrupt code.

You generate an input event by passing an IOStdReq to the device with IND_WRITEEVENT set in io_Command, a pointer to an InputEvent structure set in io_Data and the length of the structure set in io_Length.

<syntaxhighlight>
struct InputEvent *FakeEvent;
struct IOStdReq *InputIO;

InputIO->io_Data = (APTR)FakeEvent;
InputIO->io_Length = sizeof(struct InputEvent);
InputIO->io_Command = IND_WRITEEVENT;
IExec->DoIO((struct IORequest *)InputIO);
</syntaxhighlight>

{{Note|title=You Know What Happens When You Assume|text=This command propagates the input event through the handler chain. The handlers may link other events onto the end of this event or modify the contents of the data structure you constructed in any way they wish. Therefore, do not assume any of the data will be the same from event to event.}}

=== Setting the Position of the Mouse ===

One use of writing input events to the input device is to set the position of the mouse pointer. The mouse pointer can be positioned by using the input classes IECLASS_POINTERPOS and IECLASS_NEWPOINTERPOS.

There are two ways to set the position of the mouse pointer using the input class IECLASS_POINTERPOS:

* At an absolute position on the current screen.
* At a position relative to the current mouse pointer position on the current screen.

In both cases, you set the Class field of the InputEvent structure to IECLASS_POINTERPOS, ie_X with the new x-coordinate and ie_Y with the new y-coordinate. Absolute positioning is done by setting ie_Qualifier to 0 and relative positioning is done by setting ie_Qualifier to IEQUALIFIER_RELATIVEMOUSE.

Once the proper values are set, pass an IOStdReq to the input device with a pointer to the InputEvent structure set in io_Data and io_Command set to IND_WRITEEVENT.

There are three ways to set the mouse pointer position using IECLASS_NEWPOINTERPOS:

* At an absolute x-y coordinate on a screen—you specify the exact location of the pointer and which screen.
* At an relative x-y coordinate—you specify where it will go in relation to the current pointer position and which screen.
* At a normalized position on a tablet device—you specify the maximum x-value and y-value of the tablet and an x-y coordinate between them and the input device will normalize it to fit.

The basic steps required are the same for all three methods.

* Get a pointer to the screen where you want to position the pointer. This is not necessary for the tablet device.
* Set up a structure to indicate the new position of the pointer.

For absolute and relative positioning, you set up an IEPointerPixel structure with iepp_Position.X set to the new x-coordinate, iepp_Position.Y set to the new y-coordinate and iepp_Screen set to the screen pointer. You set up an InputEvent structure with ie_SubClass set to IESUBCLASS_PIXEL, a pointer to the IEPointerPixel structure set in ie_EventAddress, IECLASS_NEWPOINTERPOS set in Class, and ie_Qualifier set to either IEQUALIFIER_RELATIVEMOUSE for relative positioning or 0 for absolute positioning.

For tablet positioning, you set up an IEPointerTablet structure with iept_Range.X set to the maximum x-coordinate and iept_Range.Y set to the maximum y-coordinate, and iept_Value.X set to the new x-coordinate and iept_Value.Y set to the new y-coordinate. You set up an InputEvent structure with a pointer to the IEPointerTablet structure set in ie_EventAddress, ie_SubClass to IESUBCLASS_TABLET and Class set to IECLASS_NEWPOINTERPOS.

Finally, for all three methods, pass an IOStdReq to the device with a pointer to the InputEvent structure set in io_Data and io_Command set to IND_WRITEEVENT.

The following example sets the mouse pointer at an absolute position on a public screen using IECLASS_NEWPOINTERPOS.

<syntaxhighlight>
/*
* Set_Mouse.c
*
* This example sets the mouse at x=100 and y=200
*
* Run from CLI only
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <devices/input.h>
#include <devices/inputevent.h>
#include <intuition/screens.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/intuition.h>

struct IntuitionIFace *IIntuition = NULL;

int main()
{
struct MsgPort *InputMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);
if (InputMP != NULL)
{
struct InputEvent *FakeEvent = IExec->AllocVecTags(sizeof(struct InputEvent),
AVT_Type, MEMF_SHARED,
TAG_END);

if (FakeEvent != NULL)
{
struct IEPointerPixel *NeoPix = IExec->AllocVecTags(sizeof(struct IEPointerPixel),
AVT_Type, MEMF_SHARED,
TAG_END);

if (NeoPix != NULL)
{
struct IOStdReq *InputIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, InputMP,
TAG_END);

if (InputIO != NULL)
{
if (!IExec->OpenDevice("input.device", NULL, (struct IORequest *)InputIO, NULL))
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuition != NULL)
{
struct Screen *PubScreen;
/* Get pointer to screen and lock screen */
if (PubScreen = (struct Screen *)IIntuition->LockPubScreen(NULL))
{
/* Set up IEPointerPixel fields */
NeoPix->iepp_Screen = (struct Screen *)PubScreen; /* WB screen */
NeoPix->iepp_Position.X = 100; /* put pointer at x = 100 */
NeoPix->iepp_Position.Y = 200; /* put pointer at y = 200 */

/* Set up InputEvent fields */
FakeEvent->ie_EventAddress = (APTR)NeoPix; /* IEPointerPixel */
FakeEvent->ie_NextEvent = NULL;
FakeEvent->ie_Class = IECLASS_NEWPOINTERPOS; /* new mouse pos */
FakeEvent->ie_SubClass = IESUBCLASS_PIXEL; /* on pixel */
FakeEvent->ie_Code = IECODE_NOBUTTON;
FakeEvent->ie_Qualifier = 0; /* absolute positioning */

InputIO->io_Data = (APTR)FakeEvent; /* InputEvent */
InputIO->io_Length = sizeof(struct InputEvent);
InputIO->io_Command = IND_WRITEEVENT;
IExec->DoIO((struct IORequest *)InputIO);

IIntuition->UnlockPubScreen(NULL, PubScreen); /* Unlock screen */
}
else
IDOS->Printf("Could not get pointer to screen\n");
}
else
IDOS->Printf("Error: Could not open intuition.library\n");

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

IExec->CloseDevice((struct IORequest *)InputIO);
}
else
IDOS->Printf("Error: Could not open input.device\n");

IExec->FreeSysObject(ASOT_IOREQUEST, InputIO);
}
else
IDOS->Printf("Error: Could not create IORequest\n");

IExec->FreeVec(NeoPix);
}
else
IDOS->Printf("Error: Could not allocate memory for NeoPix\n");

IExec->FreeVec(FakeEvent);
}
else
IDOS->Printf("Error: Could not allocate memory for FakeEvent\n");

IExec->FreeSysObject(ASOT_PORT, InputMP);
}
else
IDOS->Printf("Error: Could not create message port\n");

return 0;
}
</syntaxhighlight>

== Setting the Key Repeat Threshold ==

The key repeat threshold is the number of seconds and microseconds a user must hold down a key before it begins to repeat. This delay is normally set by the Preferences tool or by Intuition when it notices that the Preferences have been changed, but you can also do it directly through the input device.

You set the key repeat threshold by passing a TimeRequest with IND_SETTHRESH set in io_Command and the number of seconds to delay set in Seconds and the number of microseconds to delay set in Microseconds.

<syntaxhighlight>
#include <devices/timer.h>

struct TimeRequest *InputTime; /* Initialize with AllocSysObject(ASOT_IOREQUEST) before using */

InputTime->Time.Seconds = 1; /* 1 second */
InputTime->Time.Microseconds = 500000; /* 500,000 microseconds */
InputTime->Request.io_Command = IND_SETTHRESH;
IExec->DoIO((struct IORequest *)InputTime);
</syntaxhighlight>

The code above will set the key repeat threshold to 1.5 seconds.

== Setting the Key Repeat Interval ==

The key repeat interval is the time period, in seconds and microseconds, between key repeat events once the initial key repeat threshold has elapsed. (See "Setting the Key Repeat Threshold" above.) Like the key repeat threshold, this is normally issued by Intuition and preset by the Preferences tool.

You set the key repeat interval by passing a TimeRequest with IND_SETPERIOD set in io_Command and the number of seconds set in Seconds and the number of microseconds set in Microseconds.

<syntaxhighlight>
struct TimeRequest *InputTime; /* Initialize with AllocSysObject(ASOT_IOREQUEST) before using */

InputTime->Time.Seconds = 0;
InputTime->Time.Microseconds = 12000; /* 0.012 seconds */
InputTime->Request.io_Command = IND_SETPERIOD;
IExec->DoIO((struct IORequest *)InputTime);
</syntaxhighlight>

The code above sets the key repeat interval to 0.012 seconds.

{{Note|title=The Right Tool For The Right Job|text=As previously stated, you ''must'' use a TimeRequest structure with IND_SETTHRESH and IND_SETPERIOD.}}

== Determining the Current Qualifiers ==

Some applications need to know whether the user is holding down a qualifier key or a mouse button during an operation. To determine the current qualifiers, you call the input device function PeekQualifier().

PeekQualifier() returns what the input device ''considers'' to be the current qualifiers at the time PeekQualifier() is called (e.g., keyboard qualifiers and mouse buttons). This does not include any qualifiers which have been added, removed or otherwise modified by input handlers.

In order to call the function, you must set a pointer to the input device base address and get the interface. Once you set the interface pointer, you can call the function. ''You must open the device in order to access the device base address and interface.''

PeekQualifier() returns an unsigned word with bits set according to the qualifiers in effect at the ''time'' the function is called. It takes no parameters.

<syntaxhighlight>
int main()
{
struct IOStdReq *InputIO; /* I/O request block */
uint16 Quals; /* qualifiers */
.
.
.
if (!IExec->OpenDevice("input.device", NULL, (struct IORequest *)InputIO, NULL))
{
/* Set input device base address in InputBase */
struct Library *InputBase = (struct Library *)InputIO->io_Device;
struct InputIFace *IInput = (struct InputIFace *)IExec->GetInterface(InputBase, "main", 1, NULL);

/* Call the function */
Quals = IInput->PeekQualifier();
.
.
.
IExec->DropInterface((struct Interface *)IInput);
IExec->CloseDevice(InputIO);
}
}
</syntaxhighlight>

The qualifiers returned are listed in the table below.
{| class="wikitable"
! Bit
! Qualifier
! Key or Button
|-
| 0 || IEQUALIFIER_LSHIFT || Left Shift
|-
| 1 || IEQUALIFIER_RSHIFT || Right Shift
|-
| 2 || IEQUALIFIER_CAPSLOCK || Caps Lock
|-
| 3 || IEQUALIFIER_CONTROL || Control
|-
| 4 || IEQUALIFIER_LALT || Left Alt
|-
| 5 || IEQUALIFIER_RALT || Right Alt
|-
| 6 || IEQUALIFIER_LCOMMAND || Left-Amiga
|-
| 7 || IEQUALIFIER_RCOMMAND || Right-Amiga
|-
| 12 || IEQUALIFIER_MIDBUTTON || Middle Mouse
|-
| 13 || IEQUALIFIER_RBUTTON || Right Mouse
|-
| 14 || IEQUALIFIER_LEFTBUTTON || Left Mouse
|}

== Input Device and Intuition ==

There are several ways to receive information from the various devices that are part of the input device. The first way is to communicate directly with the device. This method is not recommended while the input device task is running – which is most of the time. The second way is to become a handler for the stream of events which the input device produces. That method is shown above.

The third method of getting input from the input device is to retrieve the data from the console device or from the IDCMP (Intuition Direct Communications Message Port). These are the preferred methods for applications in a multitasking environment because each application can receive juts its own input (i.e., only the input which occurs when one of its window is active). See the [[Intuition_Input_and_Output_Methods|Intuition Input and Output Methods]] for more information on IDCMP messages. See [[Console_Device|Console Device]] for more information on console device I/O.

== Example Input Device Program ==

=== Swap_Buttons.c ===

<syntaxhighlight>
#include <exec/types.h>
#include <exec/memory.h>
#include <exec/interrupts.h>
#include <devices/input.h>
#include <intuition/intuition.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/intuition.h>

struct IntuitionIFace *IIntuition = NULL;

UBYTE NameString[] = "Swap Buttons";

struct NewWindow mywin={50,40,124,18,0,1,CLOSEWINDOW,
WINDOWDRAG|WINDOWCLOSE|SIMPLE_REFRESH|NOCAREREFRESH,
NULL,NULL,NameString,NULL,NULL,0,0,0,0,WBENCHSCREEN};

extern VOID ButtonSwap();

/*
* This routine opens a window and waits for the one event that
* can happen (CLOSEWINDOW) This is just to let the user play with
* the swapped buttons and then close the program...
*/
VOID WaitForUser(VOID)
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace *)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuition != NULL)
{
struct Window *win = IIntuition->OpenWindow(&mywin);
if (win != NULL)
{
IExec->WaitPort(win->UserPort);
IExec->ReplyMsg(IExec->GetMsg(win->UserPort));

IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface *)IIntuition);
IExec->CloseLibrary(IntuitionBase);
}

int main()
{
struct MsgPort *inputPort = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (inputPort != NULL)
{
struct Interrupt *inputHandler = IExec->AllocSysObjectTags(ASOT_INTERRUPT,
ASOINTR_Code, ButtonSwap,
TAG_END);

if (inputHandler != NULL)
{
struct IOStdReq *inputReqBlk = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, inputPort,
TAG_END);

if (inputReqBlk != NULL)
{
if (!IExec->OpenDevice("input.device", NULL,
(struct IORequest *)inputReqBlk, NULL))
{
inputHandler->is_Node.ln_Pri = 100;
inputHandler->is_Node.ln_Name = NameString;

inputReqBlk->io_Data = (APTR)inputHandler;
inputReqBlk->io_Command = IND_ADDHANDLER;
IExec->DoIO((struct IORequest *)inputReqBlk);

WaitForUser();

inputReqBlk->io_Data = (APTR)inputHandler;
inputReqBlk->io_Command = IND_REMHANDLER;
IExec->DoIO((struct IORequest *)inputReqBlk);

IExec->CloseDevice((struct IORequest *)inputReqBlk);
}
else
IDOS->Printf("Error: Could not open input.device\n");

IExec->FreeSysObject(ASOT_IOREQUEST, inputReqBlk);
}
else
IDOS->Printf("Error: Could not create I/O request\n");

IExec->FreeSysObject(ASOT_INTERRUPT, inputHandler);
}
else
IDOS->Printf("Error: Could not allocate interrupt\n");

IExec->FreeSysObject(ASOT_PORT, inputPort);
}
else
IDOS->Printf("Error: Could not create message port\n");

return 0;
}
</syntaxhighlight>

=== InputHandler.c ===

<pre>
struct InputEvent *ButtonSwap(struct InputEvent *eventList, struct MsgPort *port)
{
/*
* Since the event list could be a linked list, we start a loop
* here to handle all of the events passed to us.
*/
struct InputEvent *currEvent = eventList;
while (currEvent) /* Do some more. */
{
/*
* Since we are changing left and right mouse buttons, we need to make
* sure that we change the qualifiers on all of the messages. The
* left and right mouse buttons are tracked in the message qualifiers
* for use in such things as dragging. To make sure that we continue
* to drag correctly, we change the qualifiers.
*
* Save a copy
*/

uint16 qualActual = currEvent->ie_Qualifier, qualFinal = qualActual;
int RBUTTON = 1<<IEQUALIFIER_RBUTTON;
int LBUTTON = 1<<IEQUALIFIER_LEFTBUTTON;

if (RBUTTON & qualActual) /* Check for right */
{
qualFinal |= LBUTTON; /* Set the left */
}
else
{
qualFinal &= ~LBUTTON; /* Clear the left */
}

if (LBUTTON & qualActual) /* Check for left */
{
qualFinal |= RBUTTON; /* Set the right */
}
else
{
qualFinal &= ~RBUTTON; /* Set the right */
}

currEvent->ie_Qualifier = qualFinal; /* Save back */

/*
* The actual button up/down events are transmitted as the
* code field in RAWMOUSE events. The code field must the be
* checked and modified when needed on RAWMOUSE events. If the
* event is not a RAWMOUSE, we are done with it.
*/
if (IECLASS_RAWMOUSE == currEvent->ie_Class) /* Check for mouse */
{
/* Get code */
/* Save a copy */
/* We do not care if it is an UP or DOWN click */
uint16 codeActual = currEvent->ie_Code, codeFinal = (IECODE_UP_PREFIX-0x1) & codeActual;

/* Check for left/right */
if (IECODE_LBUTTON & codeActual || IECODE_RBUTTON & codeActual)
{
/* If so, swap */
/* Flip bottom bit */
codeFinal = 0x1 ^ codeActual;
currEvent->ie_Code = codeFinal;
}
}

currEvent=currEvent->ie_NextEvent; /* Get next event */
}
return eventList;
}
</pre>

== Additional Information on the Input Device ==

Additional programming information on the input device can be found in the include files and the autodocs for the input device. Both are contained in the SDK.

{| class="wikitable"
! Includes
|-
| devices/input.h
|-
| devices/inputevent.h
|}

{| class="wikitable"
! AutoDocs
|-
| input.doc
|}

Input Device

2023-10-30T00:26:50Z

Ryan Dixon: Change from the 68k Reference Manual example to more generic C

[[Category:Devices|Input]]{{CodeReview}}
== Input Device ==

The input device is the central collection point for input events disseminated throughout the system. The best way to describe the input device is a manager of a stream with feeders. The input device itself and other modules such as the file system add events to the stream; so do input device “users”—programs or other devices that use parts of the stream or change it in some way. Feeders of the input device include the keyboard, timer and gameport devices. The keyboard, gameport, and timer devices are special cases in that the input device opens them and asks them for input. Users of the input device include Intuition and the console device.

== Input Device Commands and Functions ==

{| class="wikitable"
! Command
! Command Operation
|-
| CMD_FLUSH || Purge all active and queued requests for the input device.
|-
| CMD_RESET || Reset the input port to its initialized state. All active and queued I/O requests will be aborted. Restarts the device if it has been stopped.
|-
| CMD_START || Restart the currently active input (if any) and resume queued I/O requests.
|-
| CMD_STOP || Stop any currently active input and prevent queued I/O requests from starting.
|-
| IND_ADDEVENT || Propagate an input event to all handlers, updating event qualifiers.
|-
| IND_ADDHANDLER || Add an input-stream handler into the handler chain.
|-
| IND_ADDNOTIFY || Add a hook which will be invoked whenever a configuration option changes.
|-
| IND_GETHANDLERLIST || Obtain a pointer to the list of input handlers.
|-
| IND_GETKDEVICE || Query the name and unit number of the device keyboard input events are collected from.
|-
| IND_GETMDEVICE || Query the name and unit number of the device mouse input events are collected from.
|-
| IND_GETPERIOD || Get the key repeat period.
|-
| IND_GETTHRESH || Get the key repeat threshold.
|-
| IND_IMMEDIATEADDNOTIFY || Add a hook which will be invoked whenever a configuration option changes. The hook will be invoked on the current configuration first.
|-
| IND_REMHANDLER || Remove an input-stream handler from the handler chain.
|-
| IND_REMOVENOTIFY || Remove a hook previously installed with the IND_ADDNOTIFY command.
|-
| IND_SETKDEVICE || Choose the device to collect keyboard input events from.
|-
| IND_SETMDEVICE || Choose the device to collect mouse input events from.
|-
| IND_SETMPORT || Set the controller port to which the mouse is connected.
|-
| IND_SETMTRIG || Set conditions that must be met by a mouse before a pending read request will be satisfied.
|-
| IND_SETMTYPE || Set the type of device at the mouse port.
|-
| IND_SETPERIOD || Set the period at which a repeating key repeats.
|-
| IND_SETTHRESH || Set the repeating key hold-down time before repeat starts.
|-
| IND_WRITEEVENT || Propagate an input event stream to all devices.
|}

{| class="wikitable"
|+ Input Device Functions
| PeekQualifier() || Return the input device’s current qualifiers.
|}

== Device Interface ==

The input device operates like the other Amiga devices. To use it, you must first open the input device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

A number of structures are used by the input device to do its processing. Some are used to pass commands and data to the device, some are used to describe input events like mouse movements and key depressions, and one structure is used to describe the environment for input event handlers.

The I/O request used by the input device for most commands is IOStdReq.

<syntaxhighlight>
struct IOStdReq
{
struct Message io_Message; /* message reply port */
struct Device *io_Device; /* device node pointer */
struct Unit *io_Unit; /* unit */
UWORD io_Command; /* input device command */
UBYTE io_Flags; /* input device flags */
BYTE io_Error; /* error code */
ULONG io_Length; /* number of bytes to transfer */
APTR io_Data; /* pointer to data area */
};
</syntaxhighlight>

See the include file exec/io.h for the complete structure definition.

Two of the input device commands—IND_SETTHRESH and IND_SETPERIOD—require a time specification and ''must'' use a TimeRequest structure instead of an IOStdReq.

<syntaxhighlight>
struct TimeRequest
{
struct IORequest Request;
struct TimeVal Time;
};
</syntaxhighlight>

As you can see, the TimeRequest structure includes an IORequest structure. The io_Command field of the IORequest indicates the command to the input device and the TimeVal structure sets the time values. See the include file devices/timer.h for the complete structure definition.

{{Note|title=In Case You Feel Like Reinventing the Wheel...|text=You could define a “super-IORequest” structure for the input device which would combine the IOStdReq fields with the TimeVal structure of the TimeRequest structure.}}

=== Opening the Input Device ===

Three primary steps are required to open the input device:

* Create a message port using AllocSysObject() and ASOT_PORT type. Reply messages from the device must be directed to a message port.
* Create an extended I/O request structure of type IOStdReq or TimeRequest using AllocSysObject() and ASOT_IOREQUEST type. The I/O request created by the AllocSysObject() function will be used to pass commands and data to the input device.
* Open the Input device. Call OpenDevice(), passing the I/O request.

<syntaxhighlight>
struct MsgPort *InputMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (InputMP != NULL)
{
struct IOStdReq *InputIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, InputMP,
TAG_END);

if (ClipIO != NULL)
{
if (IExec->OpenDevice("input.device", 0, (struct IORequest *)InputIO, 0))
IDOS->Printf("input.device did not open\n");
</syntaxhighlight>

The above code will work for all the input device commands except for the ones which require a time specification. For those, the code would look like this:

<syntaxhighlight>
#include <devices/timer.h>

struct MsgPort *InputMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (InputMP != NULL)
{
struct TimeRequest *InputIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct TimeRequest),
ASOIOR_ReplyPort, InputMP,
TAG_END);

if (ClipIO != NULL)
{
if (IExec->OpenDevice("input.device", 0, (struct IORequest *)InputIO, 0))
IDOS->Printf("input.device did not open\n");
</syntaxhighlight>

=== Input Device Event Types ===

The input device is automatically opened by the console device when the system boots. When the input device is opened, a task named “input.device” is started. The input device task communicates directly with the keyboard device to obtain raw key events. It also communicates with the gameport device to obtain mouse button and mouse movement events and with the timer device to obtain time events. In addition to these events, you can add your own input events to the input device, to be fed to the handler chain (see below).

The keyboard device is accessible directly (see [[Keyboard_Device|Keyboard Device]]). However, once the input.device task has started, you should not read events from the keyboard device directly, since doing so will deprive the input device of the events and confuse key repeating.

The gameport device has two units. As you view the Amiga, looking at the gameport connectors, the left connector is assigned as the primary mouse input for Intuition and contributes gameport input events to the input event stream.

The right connector is handled by the other gameport unit and is currently unassigned. While the input device task is running, that task expects to read the input from the left connector. Direct use of the gameport device is covered in [[Gameport_Device|Gameport Device]].

The timer device is used to generate time events for the input device. It is also used to control key repeat rate and key repeat threshold. The timer device is a shared-access device and is described in [[Timer_Device|Timer Device]].

The device-specific commands are described below. First though, it may be helpful to consider the types of input events that the input device deals with. An input event is a data structure that describes the following:

* The class of the event — often describes the device that generated the event.
* The subclass of the event — space for more information if needed.
* The code — keycode if keyboard, button information if mouse, others.
* A qualifier such as “Alt key also down,”or “key repeat active”.
* A position field that contains a data address or a mouse position count.
* A time stamp, to determine the sequence in which the events occurred.
* A link-field by which input events are linked together.
* The class, subclass, code and qualifier of the previous down key.

The full definitions for each field can be found in the include file devices/inputevent.h. You can find more information about input events in [[Gameport_Device|Gameport Device]] and [[Console_Device|Console Device]].

The various types of input events are listed below.

{| class="wikitable"
|+ Input Device Event Types
| IECLASS_NULL || A NOP input event
|-
| IECLASS_RAWKEY || A raw keycode from the keyboard device
|-
| IECLASS_RAWMOUSE || The raw mouse report from the gameport device
|-
| IECLASS_EVENT || A private console event
|-
| IECLASS_POINTERPOS || A pointer position report
|-
| IECLASS_TIMER || A timer event
|-
| IECLASS_GADGETDOWN || Select button pressed down over a gadget (address in ie_EventAddress)
|-
| IECLASS_GADGETUP || Select button released over the same gadget (address in ie_EventAddress)
|-
| IECLASS_REQUESTER || Some requester activity has taken place.
|-
| IECLASS_MENULIST || This is a menu number transmission (menu number is in ie_Code)
|-
| IECLASS_CLOSEWINDOW || User has selected the active window’s Close Gadget
|-
| IECLASS_SIZEWINDOW || This window has a new size
|-
| IECLASS_REFRESHWINDOW || The window pointed to by ie_EventAddress needs to be refreshed
|-
| IECLASS_NEWPREFS || New preferences are available
|-
| IECLASS_DISKREMOVED || The disk has been removed
|-
| IECLASS_DISKINSERTED || The disk has been inserted
|-
| IECLASS_ACTIVEWINDOW || The window is about to be been made active
|-
| IECLASS_INACTIVEWINDOW || The window is about to be made inactive
|-
| IECLASS_NEWPOINTERPOS || Extended-function pointer position report
|-
| IECLASS_MENUHELP || Help key report during Menu session
|-
| IECLASS_CHANGEWINDOW || The Window has been modified with move, size, zoom, or change
|}

There is a difference between simply receiving an input event from a device and actually becoming a handler of an input event stream. A handler is a routine that is passed an input event list. It is up to the handler to decide if it can process the input events. If the handler does not recognize an event, it leaves it undisturbed in the event list.

{{Note|title=It All Flows Downhill|text=Handlers can themselves generate new linked lists of events which can be passed down to lower priority handlers.}}

The InputEvent structure is used by the input device to describe an input event such as a keypress or a mouse movement.

<syntaxhighlight>
struct InputEvent
{
struct InputEvent *ie_NextEvent; /* the chronologically next event */
UBYTE ie_Class; /* the input event class */
UBYTE ie_SubClass; /* optional subclass of the class */
UWORD ie_Code; /* the input event code */
UWORD ie_Qualifier; /* qualifiers in effect for the event*/
union
{
struct
{
WORD ie_x; /* the pointer position for the event*/
WORD ie_y;
} ie_xy;
APTR ie_addr; /* the event address */
struct
{
UBYTE ie_prev1DownCode; /* previous down keys for dead */
UBYTE ie_prev1DownQual; /* key translation: the ie_Code */
UBYTE ie_prev2DownCode; /* & low byte of ie_Qualifier for */
UBYTE ie_prev2DownQual; /* last & second last down keys */
} ie_dead;
} ie_position;
struct timeval ie_TimeStamp; /* the system tick at the event */
};
</syntaxhighlight>

The IEPointerPixel and IEPointerTablet structures are used to set the mouse position with the IECLASS_NEWPOINTERPOS input event class.

<syntaxhighlight>
struct IEPointerPixel
{
struct Screen *iepp_Screen; /* pointer to an open screen */
struct
{ /* pixel coordinates in iepp_Screen */
WORD X;
WORD Y;
} iepp_Position;
};

struct IEPointerTablet
{
struct
{
UWORD X;
UWORD Y;
} iept_Range; /* 0 is min, these are max */
struct
{
UWORD X;
UWORD Y;
} iept_Value; /* between 0 and iept_Range */

WORD iept_Pressure; /* -128 to 127 (unused, set to 0) */
};
</syntaxhighlight>

See the include file devices/inputevent.h for the complete structure definitions.

For input device handler installation, the Interrupt structure is used.

<syntaxhighlight>
struct Interrupt
{
struct Node is_Node;
APTR is_Data; /* server data segment */
VOID (*is_Code)(); /* server code entry */
};
</syntaxhighlight>

See the include file exec/interrupts.h for the complete structure definition.

=== Closing the Input Device ===

Each OpenDevice() must eventually be matched by a call to CloseDevice(). All I/O requests must be complete before CloseDevice(). If any requests are still pending, abort them with AbortIO():

<syntaxhighlight>
if (!(IExec->CheckIO(InputIO)))
{
IExec->AbortIO(InputIO); /* Ask device to abort request, if pending */
}
IExec->WaitIO(InputIO); /* Wait for abort, then clean up */
IExec->CloseDevice((struct IORequest *)InputIO);
</syntaxhighlight>

== Using the Mouse Port With the Input Device ==

To get mouse port information you must first set the current mouse port by passing an IOStdReq to the device with IND_SETMPORT set in io_Command and a pointer to a byte set in io_Data. If the byte is set to 0 the left controller port will be used as the current mouse port; if it is set to 1, the right controller port will be used.

<syntaxhighlight>
int8 port = 1; /* set mouse port to right controller */

InputIO->io_Data = &port;
InputIO->io_Flags = IOF_QUICK;
InputIO->io_Length = 1;
InputIO->io_Command = IND_SETMPORT;
IExec->BeginIO((struct IORequest *)InputIO);
if (InputIO->io_Error)
IDOS->Printf("\nSETMPORT failed %ld\n", InputIO->io_Error);
</syntaxhighlight>

{{Note|title=Put That Back!|text=The default mouse port is the left controller. Don’t forget to set the mouse port back to the left controller before exiting if you change it to the right controller during your application.}}

=== Setting the Conditions for a Mouse Port Report ===

You set the conditions for a mouse port report by passing an IOStdReq to the device with IND_SETMTRIG set in io_Command, the address of a GamePortTrigger structure set in io_Data and the length of the structure set in io_Length.

<syntaxhighlight>
struct GamePortTrigger InputTR;

InputIO->io_Data = (APTR)InputTR; /* set trigger conditions */
InputIO->io_Command = IND_SETMTRIG; /* from InputTR */
InputIO->io_Length = sizeof(struct GamePortTrigger);
IExec->DoIO(InputIO);
</syntaxhighlight>

The information needed for mouse port report setting is contained in a GamePortTrigger data structure which is defined in the include file devices/gameport.h.

<syntaxhighlight>
struct GamePortTrigger
{
UWORD gpt_Keys; /* key transition triggers */
UWORD gpt_Timeout; /* time trigger (vertical blank units) */
UWORD gpt_XDelta; /* X distance trigger */
UWORD gpt_YDelta; /* Y distance trigger */
};
</syntaxhighlight>

See [[Gameport Device]] for a full description of setting mouse port trigger conditions.

== Adding an Input Handler ==

You add an input-stream handler to the input chain by passing an IOStdReq to the device with IND_ADDHANDLER set in io_Command and a pointer to an Interrupt structure set in io_Data.

<syntaxhighlight>
struct Interrupt *InputHandler;
struct IOStdReq *InputIO

InputHandler->is_Code = ButtonSwap; /* Address of code */
InputHandler->is_Data = NULL; /* User Value passed in A1 */
InputHandler->is_Node.ln_Pri = 100; /* Priority in food chain */
InputHandler->is_Node.ln_Name = NameString; /* Name of handler */

InputIO->io_Data = (APTR)inputHandler; /* Point to the structure */
InputIO->io_Command = IND_ADDHANDLER; /* Set command ... */
IExec->DoIO((struct IORequest *)InputIO); /* DoIO( ) the command */
</syntaxhighlight>

Intuition is one of the input device handlers and normally distributes most of the input events.

Intuition inserts itself at priority position 50. The console device sits at priority position 0. You can choose the position in the chain at which your handler will be inserted by setting the priority field in the list-node part of the interrupt data structure you pass to this routine.

{{Note|title=Speed Saves|text=''Any'' processing time expended by a handler subtracts from the time available before the next event happens. Therefore, handlers for the input stream ''must'' be fast.}}

=== Rules for Input Device Handlers ===

The following rules should be followed when you are designing an input handler:

* If an input handler is capable of processing a specific kind of an input event and that event has no links (ie_NextEvent = 0), the handler can end the handler chain by returning a NULL (0) value.

* If there are multiple events linked together, the handler is free to unlink an event from the input event chain, thereby passing a shorter list of events to subsequent handlers. The starting address of the modified list is the return value.

* If a handler wishes to add new events to the chain that it passes to a lower-priority handler, it may initialize memory to contain the new event or event chain. The handler, when it again gets control on the next round of event handling, should assume nothing about the current contents of the memory blocks attached to the event chain. Lower priority handlers may have modified the memory as they handled their part of the event. The handler that allocates the memory for this purpose should keep track of the starting address and the size of this memory chunk so that the memory can be returned to the free memory list when it is no longer needed.

Your handler routine should be structured similar to the following pseudo-language statement:

<syntaxhighlight>
newEventChain = yourHandlerCode(oldEventChain, yourHandlerData);
</syntaxhighlight>

where:

; yourHandlerCode
: is the entry point to your routine.
; oldEventChain
: is the starting address for the current chain of input events.
; yourHandlerData
: is a user-definable value, usually a pointer to some data structure your handler requires.
; newEventChain
: is the starting address of an event chain which you are passing to the next handler, if any.

When your handler code is called, the event chain and the handler data is passed in. When your code returns, it should return the pointer to the event chain. If all of the events were removed by the routine, return NULL. A NULL (0) value terminates the handling thus freeing more CPU resources.

Memory that you use to describe a new input event that you have added to the event chain is available for reuse or deallocation when the handler is called again or after the IND_REMHANDLER command for the handler is complete. There is no guarantee that any field in the event is unchanged since a handler may change any field of an event that comes through the food chain.

Because IND_ADDHANDLER installs a handler in any position in the handler chain, it can, for example, ignore specific types of input events as well as act upon and modify existing streams of input. It can even create new input events for Intuition or other programs to interpret.

=== Removing an Input Handler ===

You remove a handler from the handler chain by passing an IOStdReq to the device IND_REMHANDLER set in io_Command and a pointer to the Interrupt structure used to add the handler.

<syntaxhighlight>
struct Interrupt *InputHandler;
struct IOStdReq *InputIO;

InputIO->io_Data = (APTR)InputHandler; /* Which handler to REM */
InputIO->io_Command = IND_REMHANDLER; /* The REM command */
IExec->DoIO((struct IORequest *)InputIO); /* Send the command */
</syntaxhighlight>

== Writing Events to the Input Device Stream ==

Typically, input events are internally generated by the timer device, keyboard device, and input device.

An application can also generate an input event by setting the appropriate fields for the event in an InputEvent structure and sending it to the input device. It will then be treated as any other event and passed through to the input handler chain. However, I/O requests for IND_WRITEVENT cannot be made from interrupt code.

You generate an input event by passing an IOStdReq to the device with IND_WRITEEVENT set in io_Command, a pointer to an InputEvent structure set in io_Data and the length of the structure set in io_Length.

<syntaxhighlight>
struct InputEvent *FakeEvent;
struct IOStdReq *InputIO;

InputIO->io_Data = (APTR)FakeEvent;
InputIO->io_Length = sizeof(struct InputEvent);
InputIO->io_Command = IND_WRITEEVENT;
IExec->DoIO((struct IORequest *)InputIO);
</syntaxhighlight>

{{Note|title=You Know What Happens When You Assume|text=This command propagates the input event through the handler chain. The handlers may link other events onto the end of this event or modify the contents of the data structure you constructed in any way they wish. Therefore, do not assume any of the data will be the same from event to event.}}

=== Setting the Position of the Mouse ===

One use of writing input events to the input device is to set the position of the mouse pointer. The mouse pointer can be positioned by using the input classes IECLASS_POINTERPOS and IECLASS_NEWPOINTERPOS.

There are two ways to set the position of the mouse pointer using the input class IECLASS_POINTERPOS:

* At an absolute position on the current screen.
* At a position relative to the current mouse pointer position on the current screen.

In both cases, you set the Class field of the InputEvent structure to IECLASS_POINTERPOS, ie_X with the new x-coordinate and ie_Y with the new y-coordinate. Absolute positioning is done by setting ie_Qualifier to 0 and relative positioning is done by setting ie_Qualifier to IEQUALIFIER_RELATIVEMOUSE.

Once the proper values are set, pass an IOStdReq to the input device with a pointer to the InputEvent structure set in io_Data and io_Command set to IND_WRITEEVENT.

There are three ways to set the mouse pointer position using IECLASS_NEWPOINTERPOS:

* At an absolute x-y coordinate on a screen—you specify the exact location of the pointer and which screen.
* At an relative x-y coordinate—you specify where it will go in relation to the current pointer position and which screen.
* At a normalized position on a tablet device—you specify the maximum x-value and y-value of the tablet and an x-y coordinate between them and the input device will normalize it to fit.

The basic steps required are the same for all three methods.

* Get a pointer to the screen where you want to position the pointer. This is not necessary for the tablet device.
* Set up a structure to indicate the new position of the pointer.

For absolute and relative positioning, you set up an IEPointerPixel structure with iepp_Position.X set to the new x-coordinate, iepp_Position.Y set to the new y-coordinate and iepp_Screen set to the screen pointer. You set up an InputEvent structure with ie_SubClass set to IESUBCLASS_PIXEL, a pointer to the IEPointerPixel structure set in ie_EventAddress, IECLASS_NEWPOINTERPOS set in Class, and ie_Qualifier set to either IEQUALIFIER_RELATIVEMOUSE for relative positioning or 0 for absolute positioning.

For tablet positioning, you set up an IEPointerTablet structure with iept_Range.X set to the maximum x-coordinate and iept_Range.Y set to the maximum y-coordinate, and iept_Value.X set to the new x-coordinate and iept_Value.Y set to the new y-coordinate. You set up an InputEvent structure with a pointer to the IEPointerTablet structure set in ie_EventAddress, ie_SubClass to IESUBCLASS_TABLET and Class set to IECLASS_NEWPOINTERPOS.

Finally, for all three methods, pass an IOStdReq to the device with a pointer to the InputEvent structure set in io_Data and io_Command set to IND_WRITEEVENT.

The following example sets the mouse pointer at an absolute position on a public screen using IECLASS_NEWPOINTERPOS.

<syntaxhighlight>
/*
* Set_Mouse.c
*
* This example sets the mouse at x=100 and y=200
*
* Run from CLI only
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <devices/input.h>
#include <devices/inputevent.h>
#include <intuition/screens.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/intuition.h>

struct IntuitionIFace *IIntuition = NULL;

int main()
{
struct MsgPort *InputMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);
if (InputMP != NULL)
{
struct InputEvent *FakeEvent = IExec->AllocVecTags(sizeof(struct InputEvent),
AVT_Type, MEMF_SHARED,
TAG_END);

if (FakeEvent != NULL)
{
struct IEPointerPixel *NeoPix = IExec->AllocVecTags(sizeof(struct IEPointerPixel),
AVT_Type, MEMF_SHARED,
TAG_END);

if (NeoPix != NULL)
{
struct IOStdReq *InputIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, InputMP,
TAG_END);

if (InputIO != NULL)
{
if (!IExec->OpenDevice("input.device", NULL, (struct IORequest *)InputIO, NULL))
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuition != NULL)
{
struct Screen *PubScreen;
/* Get pointer to screen and lock screen */
if (PubScreen = (struct Screen *)IIntuition->LockPubScreen(NULL))
{
/* Set up IEPointerPixel fields */
NeoPix->iepp_Screen = (struct Screen *)PubScreen; /* WB screen */
NeoPix->iepp_Position.X = 100; /* put pointer at x = 100 */
NeoPix->iepp_Position.Y = 200; /* put pointer at y = 200 */

/* Set up InputEvent fields */
FakeEvent->ie_EventAddress = (APTR)NeoPix; /* IEPointerPixel */
FakeEvent->ie_NextEvent = NULL;
FakeEvent->ie_Class = IECLASS_NEWPOINTERPOS; /* new mouse pos */
FakeEvent->ie_SubClass = IESUBCLASS_PIXEL; /* on pixel */
FakeEvent->ie_Code = IECODE_NOBUTTON;
FakeEvent->ie_Qualifier = 0; /* absolute positioning */

InputIO->io_Data = (APTR)FakeEvent; /* InputEvent */
InputIO->io_Length = sizeof(struct InputEvent);
InputIO->io_Command = IND_WRITEEVENT;
IExec->DoIO((struct IORequest *)InputIO);

IIntuition->UnlockPubScreen(NULL, PubScreen); /* Unlock screen */
}
else
IDOS->Printf("Could not get pointer to screen\n");
}
else
IDOS->Printf("Error: Could not open intuition.library\n");

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

IExec->CloseDevice((struct IORequest *)InputIO);
}
else
IDOS->Printf("Error: Could not open input.device\n");

IExec->FreeSysObject(ASOT_IOREQUEST, InputIO);
}
else
IDOS->Printf("Error: Could not create IORequest\n");

IExec->FreeVec(NeoPix);
}
else
IDOS->Printf("Error: Could not allocate memory for NeoPix\n");

IExec->FreeVec(FakeEvent);
}
else
IDOS->Printf("Error: Could not allocate memory for FakeEvent\n");

IExec->FreeSysObject(ASOT_PORT, InputMP);
}
else
IDOS->Printf("Error: Could not create message port\n");

return 0;
}
</syntaxhighlight>

== Setting the Key Repeat Threshold ==

The key repeat threshold is the number of seconds and microseconds a user must hold down a key before it begins to repeat. This delay is normally set by the Preferences tool or by Intuition when it notices that the Preferences have been changed, but you can also do it directly through the input device.

You set the key repeat threshold by passing a TimeRequest with IND_SETTHRESH set in io_Command and the number of seconds to delay set in Seconds and the number of microseconds to delay set in Microseconds.

<syntaxhighlight>
#include <devices/timer.h>

struct TimeRequest *InputTime; /* Initialize with AllocSysObject(ASOT_IOREQUEST) before using */

InputTime->Time.Seconds = 1; /* 1 second */
InputTime->Time.Microseconds = 500000; /* 500,000 microseconds */
InputTime->Request.io_Command = IND_SETTHRESH;
IExec->DoIO((struct IORequest *)InputTime);
</syntaxhighlight>

The code above will set the key repeat threshold to 1.5 seconds.

== Setting the Key Repeat Interval ==

The key repeat interval is the time period, in seconds and microseconds, between key repeat events once the initial key repeat threshold has elapsed. (See "Setting the Key Repeat Threshold" above.) Like the key repeat threshold, this is normally issued by Intuition and preset by the Preferences tool.

You set the key repeat interval by passing a TimeRequest with IND_SETPERIOD set in io_Command and the number of seconds set in Seconds and the number of microseconds set in Microseconds.

<syntaxhighlight>
struct TimeRequest *InputTime; /* Initialize with AllocSysObject(ASOT_IOREQUEST) before using */

InputTime->Time.Seconds = 0;
InputTime->Time.Microseconds = 12000; /* 0.012 seconds */
InputTime->Request.io_Command = IND_SETPERIOD;
IExec->DoIO((struct IORequest *)InputTime);
</syntaxhighlight>

The code above sets the key repeat interval to 0.012 seconds.

{{Note|title=The Right Tool For The Right Job|text=As previously stated, you ''must'' use a TimeRequest structure with IND_SETTHRESH and IND_SETPERIOD.}}

== Determining the Current Qualifiers ==

Some applications need to know whether the user is holding down a qualifier key or a mouse button during an operation. To determine the current qualifiers, you call the input device function PeekQualifier().

PeekQualifier() returns what the input device ''considers'' to be the current qualifiers at the time PeekQualifier() is called (e.g., keyboard qualifiers and mouse buttons). This does not include any qualifiers which have been added, removed or otherwise modified by input handlers.

In order to call the function, you must set a pointer to the input device base address and get the interface. Once you set the interface pointer, you can call the function. ''You must open the device in order to access the device base address and interface.''

PeekQualifier() returns an unsigned word with bits set according to the qualifiers in effect at the ''time'' the function is called. It takes no parameters.

<syntaxhighlight>
int main()
{
struct IOStdReq *InputIO; /* I/O request block */
uint16 Quals; /* qualifiers */
.
.
.
if (!IExec->OpenDevice("input.device", NULL, (struct IORequest *)InputIO, NULL))
{
/* Set input device base address in InputBase */
struct Library *InputBase = (struct Library *)InputIO->io_Device;
struct InputIFace *IInput = (struct InputIFace *)IExec->GetInterface(InputBase, "main", 1, NULL);

/* Call the function */
Quals = IInput->PeekQualifier();
.
.
.
IExec->DropInterface((struct Interface *)IInput);
IExec->CloseDevice(InputIO);
}
}
</syntaxhighlight>

The qualifiers returned are listed in the table below.
{| class="wikitable"
! Bit
! Qualifier
! Key or Button
|-
| 0 || IEQUALIFIER_LSHIFT || Left Shift
|-
| 1 || IEQUALIFIER_RSHIFT || Right Shift
|-
| 2 || IEQUALIFIER_CAPSLOCK || Caps Lock
|-
| 3 || IEQUALIFIER_CONTROL || Control
|-
| 4 || IEQUALIFIER_LALT || Left Alt
|-
| 5 || IEQUALIFIER_RALT || Right Alt
|-
| 6 || IEQUALIFIER_LCOMMAND || Left-Amiga
|-
| 7 || IEQUALIFIER_RCOMMAND || Right-Amiga
|-
| 12 || IEQUALIFIER_MIDBUTTON || Middle Mouse
|-
| 13 || IEQUALIFIER_RBUTTON || Right Mouse
|-
| 14 || IEQUALIFIER_LEFTBUTTON || Left Mouse
|}

== Input Device and Intuition ==

There are several ways to receive information from the various devices that are part of the input device. The first way is to communicate directly with the device. This method is not recommended while the input device task is running – which is most of the time. The second way is to become a handler for the stream of events which the input device produces. That method is shown above.

The third method of getting input from the input device is to retrieve the data from the console device or from the IDCMP (Intuition Direct Communications Message Port). These are the preferred methods for applications in a multitasking environment because each application can receive juts its own input (i.e., only the input which occurs when one of its window is active). See the [[Intuition_Input_and_Output_Methods|Intuition Input and Output Methods]] for more information on IDCMP messages. See [[Console_Device|Console Device]] for more information on console device I/O.

== Example Input Device Program ==

=== Swap_Buttons.c ===

<syntaxhighlight>
#include <exec/types.h>
#include <exec/memory.h>
#include <exec/interrupts.h>
#include <devices/input.h>
#include <intuition/intuition.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/intuition.h>

struct IntuitionIFace *IIntuition = NULL;

UBYTE NameString[] = "Swap Buttons";

struct NewWindow mywin={50,40,124,18,0,1,CLOSEWINDOW,
WINDOWDRAG|WINDOWCLOSE|SIMPLE_REFRESH|NOCAREREFRESH,
NULL,NULL,NameString,NULL,NULL,0,0,0,0,WBENCHSCREEN};

extern VOID ButtonSwap();

/*
* This routine opens a window and waits for the one event that
* can happen (CLOSEWINDOW) This is just to let the user play with
* the swapped buttons and then close the program...
*/
VOID WaitForUser(VOID)
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace *)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuition != NULL)
{
struct Window *win = IIntuition->OpenWindow(&mywin);
if (win != NULL)
{
IExec->WaitPort(win->UserPort);
IExec->ReplyMsg(IExec->GetMsg(win->UserPort));

IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface *)IIntuition);
IExec->CloseLibrary(IntuitionBase);
}

int main()
{
struct MsgPort *inputPort = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (inputPort != NULL)
{
struct Interrupt *inputHandler = IExec->AllocSysObjectTags(ASOT_INTERRUPT,
ASOINTR_Code, ButtonSwap,
TAG_END);

if (inputHandler != NULL)
{
struct IOStdReq *inputReqBlk = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, inputPort,
TAG_END);

if (inputReqBlk != NULL)
{
if (!IExec->OpenDevice("input.device", NULL,
(struct IORequest *)inputReqBlk, NULL))
{
inputHandler->is_Node.ln_Pri = 100;
inputHandler->is_Node.ln_Name = NameString;

inputReqBlk->io_Data = (APTR)inputHandler;
inputReqBlk->io_Command = IND_ADDHANDLER;
IExec->DoIO((struct IORequest *)inputReqBlk);

WaitForUser();

inputReqBlk->io_Data = (APTR)inputHandler;
inputReqBlk->io_Command = IND_REMHANDLER;
IExec->DoIO((struct IORequest *)inputReqBlk);

IExec->CloseDevice((struct IORequest *)inputReqBlk);
}
else
IDOS->Printf("Error: Could not open input.device\n");

IExec->FreeSysObject(ASOT_IOREQUEST, inputReqBlk);
}
else
IDOS->Printf("Error: Could not create I/O request\n");

IExec->FreeSysObject(ASOT_INTERRUPT, inputHandler);
}
else
IDOS->Printf("Error: Could not allocate interrupt\n");

IExec->FreeSysObject(ASOT_PORT, inputPort);
}
else
IDOS->Printf("Error: Could not create message port\n");

return 0;
}
</syntaxhighlight>

=== InputHandler.c ===

<pre>
struct InputEvent *ButtonSwap(struct InputEvent *eventList, struct MsgPort *port)
{
/*
* Since the event list could be a linked list, we start a loop
* here to handle all of the events passed to us.
*/
struct InputEvent *currEvent = eventList;
while (currEvent) /* Do some more. */
{
/*
* Since we are changing left and right mouse buttons, we need to make
* sure that we change the qualifiers on all of the messages. The
* left and right mouse buttons are tracked in the message qualifiers
* for use in such things as dragging. To make sure that we continue
* to drag correctly, we change the qualifiers.
*
* Save a copy
*/

uint16 qualActual = currEvent->ie_Qualifier, qualFinal = qualActual;

if (IEQUALIFIERB_RBUTTON & qualActual) /* Check for right */
{
qualFinal |= IEQUALIFIERB_LEFTBUTTON; /* Set the left */
}
else
{
qualFinal &= ~IEQUALIFIERB_RBUTTON; /* Clear the left */
}

if (IEQUALIFIERB_LEFTBUTTON & qualActual) /* Check for left */
{
qualFinal |= IEQUALIFIERB_RBUTTON; /* Set the right */
}
else
{
qualFinal &= ~IEQUALIFIERB_LEFTBUTTON; /* Set the left */
}

currEvent->ie_Qualifier = qualFinal; /* Save back */

/*
* The actual button up/down events are transmitted as the
* code field in RAWMOUSE events. The code field must the be
* checked and modified when needed on RAWMOUSE events. If the
* event is not a RAWMOUSE, we are done with it.
*/
if (IECLASS_RAWMOUSE == currEvent->ie_Class) /* Check for mouse */
{
/* Get code */
/* Save a copy */
/* We do not care if it is an UP or DOWN click */
uint16 codeActual = currEvent->ie_Code, codeFinal = (IECODE_UP_PREFIX-0x1) & codeActual;

/* Check for left/right */
if (IECODE_LBUTTON & codeActual || IECODE_RBUTTON & codeActual)
{
/* If so, swap */
/* Flip bottom bit */
codeFinal = 0x1 ^ codeActual;
currEvent->ie_Code = codeFinal;
}
}

currEvent=currEvent->ie_NextEvent; /* Get next event */
}
return eventList;
}
</pre>

== Additional Information on the Input Device ==

Additional programming information on the input device can be found in the include files and the autodocs for the input device. Both are contained in the SDK.

{| class="wikitable"
! Includes
|-
| devices/input.h
|-
| devices/inputevent.h
|}

{| class="wikitable"
! AutoDocs
|-
| input.doc
|}