### AllocMem Usage Examples (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_0332.md Provides several examples demonstrating how to call AllocMem with different byte sizes and attribute flags, including allocating best available, cleared, chip, and public memory. ```C AllocMem(64,0L) - Allocate the best available memory AllocMem(25,MEMF_CLEAR) - Allocate the best available memory, and clear it before returning. AllocMem(128,MEMF_CHIP) - Allocate chip memory AllocMem(128,MEMF_CHIP|MEMF_CLEAR) - Allocate cleared chip memory AllocMem(821,MEMF_CHIP|MEMF_PUBLIC|MEMF_CLEAR) - Allocate cleared, public, chip memory. ``` -------------------------------- ### LINK and UNLK Application Example Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/link.md An example demonstrating the use of the LINK and UNLK instructions within a subroutine to create and manage a local workspace on the stack. It shows how to allocate space, access data within the stack frame using the frame pointer (A6), and deallocate the space before returning. ```Assembly Subrtn LINK A6,#-12 ;Create a 12-byte workspace . MOVE D3,(-8,A6) ;Access the stack frame via A6 . . UNLK A6 ;Collapse the workspace RTS ;Return from subroutine ``` -------------------------------- ### Example: Creating a Private Boopsi Class (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/MakeClass.md Provides a C example function 'initMyClass' demonstrating how to use MakeClass to create a private boopsi class. It shows defining instance data, shared user data, calling MakeClass, and initializing the class dispatcher and user data pointer. ```C /* per-object instance data defined by my class */ struct MyInstanceData { ULONG mid_SomeData; }; /* some useful table I'll share use for all objects */ UWORD myTable[] = { 5, 4, 3, 2, 1, 0 }; struct IClass * initMyClass() { ULONG __saveds myDispatcher(); ULONG hookEntry(); /* asm-to-C interface glue */ struct IClass *cl; struct IClass *MakeClass(); if ( cl = MakeClass( NULL, SUPERCLASSID, NULL, /* superclass is public */ sizeof (struct MyInstanceData), 0 )) { /* initialize the cl_Dispatcher [Hook](_012D.md) */ cl->cl_Dispatcher.h_Entry = hookEntry; cl->cl_Dispatcher.h_SubEntry = myDispatcher; cl->cl_Dispatcher.h_Data = (VOID *) 0xFACE; /* unused */ cl->cl_UserData = (ULONG) myTable; } return ( cl ); } ``` -------------------------------- ### Example Calls to SetExcept (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/SetExcept.md Provides examples of calling the SetExcept function to retrieve the current exception signal state and to modify specific signals. ```C SetExcept(0,0) Change a few exception signals: SetExcept($1374,$1074) ``` -------------------------------- ### Install clip region in Layer (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_0399.md This snippet provides the C function prototype for `InstallClipRegion` and illustrates its calling convention on the m68k architecture, showing how the return value is passed in register d0 and the arguments in registers a0 and a1. ```C oldclipregion = InstallClipRegion( l, region ) d0 a0 a1 struct Region *InstallClipRegion( struct Layer *, struct Region *); ``` -------------------------------- ### Example Usage of AvailFonts (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/diskfont/AvailFonts.md This C example demonstrates how to call AvailFonts to retrieve information about available fonts. It includes a loop to handle cases where the initial buffer size is insufficient, reallocating memory as needed until the function succeeds. ```C int afShortage, afSize; struct [AvailFontsHeader](_0102.md) *afh; ... afSize = 400; do { afh = (struct [AvailFontsHeader](_0102.md) *) AllocMem(afSize, 0); if (afh) { afShortage = AvailFonts(afh, afSize, AFF_MEMORY|AFF_DISK); if (afShortage) { FreeMem(afh, afSize); afSize += afShortage; } } else { fail("AllocMem of [AvailFonts](_0102.md) buffer afh failed\n"); break; } } while (afShortage); /* * if (afh) non-zero here, then: * 1. it points to a valid [AvailFontsHeader](_0102.md) * 2. it must have FreeMem(afh, afSize) called for it after use */ ``` -------------------------------- ### Example Usage - AllocRemember - C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/AllocRemember.md This C code example demonstrates the typical usage of AllocRemember. It shows how to initialize the RememberKey pointer to NULL, call AllocRemember to allocate a buffer, check if the allocation was successful, and finally call FreeRemember with the RememberKey to deallocate the memory. ```C struct Remember *RememberKey; RememberKey = NULL; buffer = AllocRemember(&RememberKey, BUFSIZE, MEMF_CHIP); if (buffer) { /* Use the buffer */ ... } FreeRemember(&RememberKey, TRUE); ``` -------------------------------- ### Sample Usage of ADDQ Instruction (Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/addq.md Provides a concrete example of the M68k ADDQ instruction, demonstrating how to add the immediate value 6 to the data register D3. ```Assembly ADDQ #6,D3 ``` -------------------------------- ### Example Two-Pass Window Refresh Handling (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/BeginRefresh.md Demonstrates handling an IDCMP_REFRESHWINDOW message for a window requiring a two-pass refresh. It shows how to use LockLayerInfo, InstallClipRegion, BeginRefresh, and EndRefresh for refreshing specific regions and managing the damage list. ```c switch ( imsg->Class ) { ... case IDCMP_REFRESHWINDOW: window = imsg->IDCMPWindow; /* this lock only needed for "two-pass" refreshing */ LockLayerInfo( &window->WScreen->LayerInfo ); /* refresh pass for region 1 */ origclip = InstallClipRegion( window->WLayer, region1 ); BeginRefresh( window ); myRefreshRegion1( window ); EndRefresh( window, FALSE ); /* refresh pass for region 2 */ InstallClipRegion( window->WLayer, region2 ); BeginRefresh( window ); myRefreshRegion2( window ); EndRefresh( window, TRUE ); /* and dispose damage list */ /* restore and unlock */ InstallClipRegion( window->WLayer, origclip ); ``` -------------------------------- ### Setting Up AmigaOS Hook in C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_012D.md This C function (`SetupHook`) provides a simple example of how to initialize a `Hook` structure. It assigns the assembly entry point (`hookEntry`), the target C function (`c_function`), and user data (`userdata`) to the appropriate fields of the hook structure. ```C SetupHook( hook, c_function, userdata ) struct Hook *hook; ULONG (*c_function)(); VOID *userdata; { ULONG (*hookEntry)(); hook->h_Entry = hookEntry; hook->h_SubEntry = c_function; hook->h_Data = userdata; } ``` -------------------------------- ### Example Application of MOVEP.L (Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/movep.md This code demonstrates using MOVEP.L to transfer a longword from data register D0 to a memory-mapped peripheral starting at address $080001. It first loads the base address into address register A0 using LEA and then performs the longword transfer using MOVEP.L with a zero offset. ```assembly LEA $080001,A0 MOVEP.L D0,0(A0) ``` -------------------------------- ### Example Usage of AbortIO (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/AbortIO.md Demonstrates a typical usage pattern for AbortIO, showing how to call it and then wait for the I/O request to complete using WaitIO before the request structure can be safely reused. ```c AbortIO(timer_request); WaitIO(timer_request); /* [Message](_0099.md) is free to be reused */ ``` -------------------------------- ### Example Usage of ExAll (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/dos/ExAll.md Demonstrates the typical usage pattern for ExAll, including allocating and initializing the ExAllControl structure, calling ExAll in a loop until all entries are processed, handling potential errors, iterating through the entries in the buffer, and freeing the control structure. ```c eac = AllocDosObject(DOS_EXALLCONTROL,NULL); if (!eac) ... ... eac->eac_LastKey = 0; do { more = ExAll(lock, EAData, sizeof(EAData), ED_FOO, eac); if ((!more) && (IoErr() != ERROR_NO_MORE_ENTRIES)) { /* ExAll failed abnormally */ break; } if (eac->eac_Entries == 0) { /* ExAll failed normally with no entries */ continue; /* ("more" is *usually* zero) */ } ead = (struct ExAllData *) EAData; do { /* use ead here */ ... /* get next ead */ ead = ead->ed_Next; } while (ead); } while (more); ... FreeDosObject(DOS_EXALLCONTROL,eac); ``` -------------------------------- ### Calling CreateTask Function in C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/_014A.md This C example demonstrates how to call the CreateTask function. It shows how to declare the function entry point using `extern void functionName();` and how to pass the task name, priority, function address, and stack size as arguments. ```c extern void functionName(); char *tname = "unique name"; task = CreateTask(tname, 0L, functionName, 4000L); ``` -------------------------------- ### Example Implementation of OpenScreenTags Stub (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/OpenScreenTagList.md An example implementation of the OpenScreenTags varargs stub function for 32-bit C parameter passing conventions. This stub calls OpenScreenTagList, casting the variable arguments pointer to a struct TagItem *. ```C struct Screen * OpenScreenTags( ns, tag1 ) struct NewScreen *ns; ULONG tag1; { struct Screen *OpenScreenTagList(); return ( OpenScreenTagList( ns, (struct TagItem *) &tag1 ) ); } ``` -------------------------------- ### Implementing EasyRequest Varargs Wrapper (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/EasyRequestArgs.md An example implementation showing how the varargs EasyRequest function can be built as a wrapper around the core EasyRequestArgs function, typically provided by the compiler or amiga.lib. ```C EasyRequest( w, es, ip, arg1 ) struct Window *w; struct EasyStruct *es; ULONG *ip; int arg1; { return ( EasyRequestArgs( w, es, ip, &arg1 ) ); } ``` -------------------------------- ### Example: Using Allocate for Custom Memory Pool (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/Allocate.md Demonstrates how to set up a custom memory pool using MemHeader and MemChunk, allocate memory blocks from it using Allocate, and then free the allocated memory using FreeMem. It shows the necessary includes and basic error handling. ```C #include #include void *AllocMem(); #define BLOCKSIZE 4096L /* Or whatever you want */ void main() { struct MemHeader *mh; struct MemChunk *mc; APTR block1; APTR block2; /* Get the MemHeader needed to keep track of our new block */ mh = (struct MemHeader *) AllocMem((long)sizeof(struct MemHeader), MEMF_CLEAR ); if( !mh ) exit(10); /* Get the actual block the above MemHeader will manage */ mc = (struct MemChunk *)AllocMem( BLOCKSIZE, 0L ); if( !mc ) { FreeMem( mh, (long)sizeof(struct MemHeader) ); exit(10); } mh->mh_Node.ln_Type = NT_MEMORY; mh->mh_Node.ln_Name = "myname"; mh->mh_First = mc; mh->mh_Lower = (APTR) mc; mh->mh_Upper = (APTR) ( BLOCKSIZE + (ULONG) mc ); mh->mh_Free = BLOCKSIZE; /* Set up first chunk in the freelist */ mc->mc_Next = NULL; mc->mc_Bytes = BLOCKSIZE; block1 = (APTR) Allocate( mh, 20L ); block2 = (APTR) Allocate( mh, 314L ); printf("mh=$%lx mc=$%lx\n",mh,mc); printf("Block1=$%lx, Block2=$%lx\n",block1,block2); FreeMem( mh, (long)sizeof(struct MemHeader) ); FreeMem( mc, BLOCKSIZE ); } ``` -------------------------------- ### Install Layer BackFill Hook - C Signature and Usage Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_039A.md This snippet shows the C function signature for InstallLayerHook and its typical usage, including the register assignments (d0, a0, a1) used in assembly calls. It illustrates how to call the function with a layer pointer and a hook pointer to install a new BackFill hook. ```c oldhook = InstallLayerHook( layer, hook ) d0 a0 a1 struct Hook *InstallLayerHook( struct Layer *, struct Hook *); ``` -------------------------------- ### TRAP Instruction Application Example (Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/trap.md An example demonstrating the use of TRAP #15 for an operating system call, specifically to display a character. It shows setting up a parameter (character code 6) in register D0 before invoking the trap. ```Assembly MOVE.B #6,D0 ;Set up the display a character parameter in D0 TRAP #15 ;Now call the operating system ``` -------------------------------- ### CreatePort Function Signature and Usage in C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/_0148.md This snippet shows the function signature for CreatePort and a typical usage example, demonstrating how to call the function and assign the result to a variable. ```C port = CreatePort(name,pri) struct MsgPort *CreatePort(STRPTR,LONG); ``` -------------------------------- ### Install View - Amiga Graphics - C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_0459.md This C function installs a new graphics view for display. It takes a pointer to a View structure, which should contain a pointer to a constructed coprocessor instruction list. This list is typically created using functions like InitVPort, MakeVPort, and MrgCop. Passing NULL will disable the view display but keep display DMA active. ```C LoadView( View ) A1 void LoadView( struct View * ); ``` -------------------------------- ### Example Usage of CreateExtIO (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/_0147.md Demonstrates how to call CreateExtIO to create an IORequest, typically used within an if statement to check for allocation success. It shows creating a temporary MsgPort and specifying the size using sizeof(struct IOExtTD). ```C if (ioReq = CreateExtIO(CreatePort(NULL,0),sizeof(struct IOExtTD))) ``` -------------------------------- ### Sample LEA Instruction Syntax - M68k Assembly Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/lea.md Provides various examples demonstrating different addressing modes used with the LEA instruction, including direct, PC-relative, and indexed addressing. ```Assembly LEA Table,A0 LEA (Table,PC),A0 LEA (-6,A0,D0.L),A6 LEA (Table,PC,D0),A6 ``` -------------------------------- ### Example Usage of AllocEntry (M68k Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/AllocEntry.md Demonstrates how to define a MemList structure in M68k assembly and call the AllocEntry function. It shows how to pass the structure address in A0 and check the return value in D0 for success or failure, specifically looking at bit 31. ```assembly MemListDecl: DS.B LN_SIZE * reserve space for list node DC.W 5 * number of entries DC.L MEMF_CLEAR * entry #0 DC.L 2 DC.L MEMF_PUBLIC * entry #1 DC.L 4 DC.L MEMF_CHIP!MEMF_CLEAR * entry #2 DC.L 8 DC.L MEMF_CLEAR * entry #3 DC.L 16 DC.L MEMF_PUBLIC!MEMF_CLEAR * entry #4 DC.L 32 start: LEA.L MemListDecl(PC),A0 JSR _LVOAllocEntry(a6) BCLR.L #31,D0 BEQ.S success ------- Type of memory that we failed on is in D0 ``` -------------------------------- ### copinit Structure Definition (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/graphics/_00AD.md Defines a structure containing initial Copper list data used for system setup, including VSync, display window, diagnostic start, sprite setup, and wait instructions. ```C /* private graphics data structure */ struct copinit { UWORD vsync_hblank[2]; UWORD diwstart[4]; UWORD diagstrt[4]; /* copper list for first bitplane */ UWORD sprstrtup[(2*8*2)]; UWORD wait14[2]; UWORD norm_hblank[2]; UWORD genloc[4]; UWORD jump[(2*2)]; UWORD wait_forever[2]; UWORD sprstop[4]; }; ``` -------------------------------- ### Get Current Task Signals State (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/SetSignal.md Example demonstrating how to retrieve the current state of all signals for the task by calling SetSignal with both the newSignals and signalMask arguments set to 0L. ```C SetSignal(0L,0L); ``` -------------------------------- ### Example: Get Largest Chip Memory (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/AvailMem.md Demonstrates how to use AvailMem to find the size of the largest contiguous block of chip memory by combining the MEMF_CHIP and MEMF_LARGEST flags. ```C AvailMem(MEMF_CHIP|MEMF_LARGEST); /* return size of largest available chip memory chunk */ ``` -------------------------------- ### Example Usage of EasyRequest in getVolume (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/EasyRequestArgs.md Demonstrates a typical use case of EasyRequest within a function that attempts to find a volume, prompting the user to insert it if not found. It shows how to handle IDCMP messages and the requester's return value. ```C Volume * getVolume( volname ) UBYTE *volname; { Volume *vptr; Volume *findVolume(); UWORD reply; ULONG iflags; iflags = IDCMP_DISKINSERTED; while ( ((vptr = findVolume( volname )) == NULL) && (EasyRequest( w, &volumeES, &iflags, volname ) != CANCEL) ) /* loop */ ; /* note that in some circumstances, you will have to re-initialize the value of 'iflags'. Here, it is either unchanged, or returned as the single IDCMPFlag value IDCMP_DISKINSERTED. If you combine multiple IDCMPFlag values in 'iflags,' only one will be returned, so you must reinitialize 'iflags' to be the combination. */ return ( vptr ); } ``` -------------------------------- ### Example: Get Exception Vector Base (m68k Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/Supervisor.md This assembly code snippet provides an example of a function suitable for use as the userFunc parameter for the Supervisor call. It demonstrates how to use the MOVEC instruction (available on 68010+ processors) to read the Vector Base Register (VBR) into data register D0. The routine correctly ends with an rte instruction as required. ```Assembly MOVECtrap: movec.l VBR,d0 ;$4e7a,$0801 rte ``` -------------------------------- ### Applying EXT Instruction with Examples (Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/ext.md Demonstrates the effect of the M68k EXT instruction on a data register (D0) for both Word and Longword sizes. It shows the initial value and the resulting value after the sign extension operation. ```Assembly [D0] = $12345678, EXT.W D0 [D0] = $12345678, EXT.L D0 ``` -------------------------------- ### Getting the process's CLI structure in C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/dos/Cli.md This snippet shows the function signature and a basic usage example for the Cli function, which retrieves the CommandLineInterface structure pointer for the current process. It returns NULL if no CLI structure exists. ```C cli_ptr = Cli() D0 struct CommandLineInterface *Cli(void) ``` -------------------------------- ### Define ExtNewWindow Structure in C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/graphics/_00D4.md Defines an extended structure for creating windows in V36 and later. It starts with the same fields as `NewWindow` and is intended for future extensions. Its use is indicated by the `WFLG_NW_EXTENDED` flag. ```C struct ExtNewWindow { WORD LeftEdge, TopEdge; WORD Width, Height; UBYTE DetailPen, BlockPen; ULONG IDCMPFlags; ULONG Flags; struct Gadget *FirstGadget; ``` -------------------------------- ### GetDefaultPubScreen Function Synopsis and Prototype (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/GetDefaultPubScreen.md Provides the assembly-like synopsis showing the register usage (A0 for the buffer) and the standard C function prototype for GetDefaultPubScreen. ```Assembly/C Synopsis GetDefaultPubScreen( Namebuff ) A0 ``` ```C Prototype VOID GetDefaultPubScreen( UBYTE * ); ``` -------------------------------- ### Syntax for OUTPUT Instruction (Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/directives/output.md Sets the output file name to when no output name was given on the command line. A special case for Devpac-compatibility is when starts with a ’.’ and an output name was already given. Then the current output name gets appended as an extension. When an extension already exists, then it is replaced. ```assembly output ``` -------------------------------- ### GetCC Function Signature and Usage - C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/GetCC.md This snippet shows the C language signature for the `GetCC` function, which returns a `UWORD` representing the 68k condition codes. It also includes an example usage demonstrating assignment to a variable and notes the return value is typically placed in register D0 according to 68k assembly conventions. ```C conditions = GetCC() D0 UWORD GetCC(void); ``` -------------------------------- ### Defining an EasyStruct Instance (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/EasyRequestArgs.md Shows how to initialize an instance of the EasyStruct structure with specific values for a 'Volume Request' requester, including the title, body text format, and gadget text format. ```C struct EasyStruct volumeES = { sizeof (struct EasyStruct), 0, "Volume Request", "Please insert volume %s in any drive.", "Retry|Cancel", }; #define CANCEL (0) ``` -------------------------------- ### Example: FlushLibrary Function (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/RemLibrary.md An example C function demonstrating how to use RemLibrary to attempt to remove a library by name from the system's library list. It uses Forbid/Permit to protect the list access. ```C /* Attempts to flush the named library out of memory. */ #include #include void FlushLibrary(name) STRPTR name; { struct Library *result; Forbid(); if(result=(struct Library *)FindName(&SysBase->LibList,name)) RemLibrary(result); Permit(); } ``` -------------------------------- ### Sample Syntax of MOVEP Instruction (Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/movep.md This snippet provides concrete examples of the MOVEP instruction syntax using specific data and address registers (D3, D5, A0, A6) and symbolic displacements (Control, Input) to demonstrate typical usage. ```assembly MOVEP D3,(Control,A0) MOVEP (Input,A6),D5 ``` -------------------------------- ### Example Usage - Partial and Complete Updates - C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_0396.md Demonstrates how to use BeginUpdate and EndUpdate for performing a two-part refresh of a layer, showing the use of the flag parameter for partial (FALSE) and complete (TRUE) updates. ```c -- begin update for first part of two-part refresh -- BeginUpdate(my_layer); -- do some refresh, but not all -- my_partial_refresh_routine(my_layer); -- end update, false (not completely done refreshing yet) -- EndUpdate(my_layer, FALSE); -- begin update for last part of refresh -- BeginUpdate(my_layer); -- do rest of refresh -- my_complete_refresh_routine(my_layer); -- end update, true (completely done refreshing now) -- EndUpdate(my_layer, TRUE); ``` -------------------------------- ### BeginUpdate Function Signature (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_038E.md The function signature for `BeginUpdate`, showing its return type, parameter, and the register usage conventions for the m68k architecture (d0 for return value, a0 for the first parameter). ```c result = BeginUpdate( l ) d0 a0 LONG BeginUpdate( struct Layer *); ``` -------------------------------- ### Multi-Precision BCD Addition Example (Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/abcd.md An example demonstrating how to use the ABCD instruction to add two nine-digit BCD numbers stored in memory using address register indirect with pre-decrementing in a loop. ```assembly LEA Number1,A0 ;A0 points at first string LEA Number2,A1 ;A1 points at second string MOVE #8,D0 ;Nine digits to add MOVE #$04,CCR ;Clear X-bit and Z-bit of the CCR LOOP ABCD -(A0),-(A1) ;Add a pair of digits DBRA D0,LOOP ;Repeat until 9 digits added ``` -------------------------------- ### Example: Using ObtainSemaphoreShared and ObtainSemaphore (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/ObtainSemaphoreShared.md This example demonstrates how to obtain a shared lock for reading data and an exclusive lock for modifying data using ObtainSemaphoreShared and ObtainSemaphore, followed by releasing the semaphore with ReleaseSemaphore. ```C ObtainSemaphoreShared(ss); /* read data */ ReleaseSemaohore(ss); ObtainSemaphore(ss); /* modify data */ ReleaseSemaohore(ss); ``` -------------------------------- ### Defining the NewWindow Structure in C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/_00D4.md This structure holds the basic parameters required to open a window using the AmigaOS Intuition library. It includes fields for position, size, pens, IDCMP flags, gadgets, title, screen type, and an extension pointer for V36+ tag items. ```C struct Image *CheckMark; UBYTE *Title; struct Screen *Screen; struct BitMap *BitMap; WORD MinWidth, MinHeight; UWORD MaxWidth, MaxHeight; /* the type variable describes the Screen in which you want this Window to * open. The type value can either be CUSTOMSCREEN or one of the * system standard Screen Types such as WBENCHSCREEN. See the * type definitions under the Screen structure. * A new possible value for this field is PUBLICSCREEN, which * defines the window as a 'visitor' window. See below for * additional information provided. */ UWORD Type; /* ------------------------------------------------------- * * extensions for V36 * if the NewWindow Flag value WFLG_NW_EXTENDED is set, then * this field is assumed to point to an array ( or chain of arrays) * of TagItem structures. See also ExtNewScreen for another * use of TagItems to pass optional data. * * see below for tag values and the corresponding data. */ struct TagItem *Extension; }; ``` -------------------------------- ### M68k OR Instruction Example - Assembly Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/or.md An example demonstrating how to use the OR instruction to set specific bits in a data register. This snippet performs a logical OR of the immediate value $F0000000 with the longword in data register D0, setting the four most significant bits. ```assembly OR.L #$F0000000,D0 ``` -------------------------------- ### Calling and Declaring MakeClass Function (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/MakeClass.md Shows the typical C syntax for calling the MakeClass function, including parameter-to-register mapping, and provides the standard C function prototype with parameter types and return type. ```C iclass = MakeClass( ClassID, SuperClassID, SuperClassPtr, D0 A0 A1 A2 InstanceSize, Flags ) D0 D1 struct IClass *MakeClass( UBYTE *, UBYTE *, struct IClass *, UWORD, ULONG ); ``` -------------------------------- ### Getting Vertical Beam Position in C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/graphics/VBeamPos.md This C snippet shows the synopsis for the VBeamPos function. It illustrates how the function might be called and its return type. The function retrieves the vertical beam position from the hardware. ```C pos = VBeamPos() d0 LONG VBeamPos( void ); ``` -------------------------------- ### Defining Amiga Window Attribute (GimmeZeroZero) in C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_00D4.md This C preprocessor macro defines a window attribute equivalent to the WFLG_GIMMEZEROZERO flag, indicating that the window's content area should start at coordinates (0,0) relative to the window's top-left corner. ```C #define WA_GimmeZeroZero (WA_Dummy + 0x2E) /* equiv. to NewWindow.Flags WFLG_GIMMEZEROZERO */ ``` -------------------------------- ### M68k ROL, ROR Syntax Examples Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/rol_ror.md Provides various syntax forms for the ROL and ROR instructions, showing how to specify the rotation count using a data register, an immediate value, or implicitly rotating by one when using an effective address. ```Assembly ROL Dx,Dy ROR Dx,Dy ROL #,Dy ROR #,Dy ROL ROR ``` -------------------------------- ### ScreenToFront Function Synopsis - C/Assembly Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/ScreenToFront.md Synopsis showing the function call format, the register used for the Screen pointer (A0) in assembly, and the C function prototype. ```C ScreenToFront( Screen ) A0 VOID ScreenToFront( struct Screen * ); ``` -------------------------------- ### General Alerts Example Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/_007F.md This comment block provides an example of how alert constants are combined to form a specific alert number. It shows how constants representing the subsystem (timer.device), general error (opening a library), and object (math.library) are logically ORed together. ```C /********************************************************************* * * General Alerts * * For example: timer.device cannot open math.library would be 0x05038015 * * Alert(AN_TimerDev|AG_OpenLib|AO_MathLib); * **********************************************************************/ ``` -------------------------------- ### InitGels Parameter Registers (m68k) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/graphics/InitGels.md Illustrates the m68k register assignments used when calling the InitGels function, mapping parameters 'head', 'tail', and 'GInfo' to registers A0, A1, and A2 respectively. ```m68k InitGels(head, tail, GInfo) A0 A1 A2 ``` -------------------------------- ### Defining Amiga Intuition ExtNewWindow Structure (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_00D4.md Defines an extended structure for creating new windows, intended for future compatibility and additional fields. It starts with the same fields as NewWindow and may contain further extensions not shown here. It is used when the WFLG_NW_EXTENDED flag is set. ```C struct ExtNewWindow { WORD LeftEdge, TopEdge; WORD Width, Height; UBYTE DetailPen, BlockPen; ULONG IDCMPFlags; ULONG Flags; struct Gadget *FirstGadget; }; ``` -------------------------------- ### BeginRefresh Function Signature and Usage (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/BeginRefresh.md Provides the function signature for BeginRefresh in C, showing the parameter type (struct Window *) and its usage in assembly (parameter in A0). It indicates the function returns VOID. ```c BeginRefresh( Window ) A0 VOID BeginRefresh( struct Window * ); ``` -------------------------------- ### Implementing sprintf using RawDoFmt (Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/RawDoFmt.md An example implementation of a simple C-style sprintf function in m68k assembly using the RawDoFmt AmigaOS function. It takes the output string pointer, format string pointer, and a pointer to the data stream (stack) as arguments. ```Assembly ; ; Simple version of the C "sprintf" function. Assumes C-style ; stack-based function conventions. ; ; long eyecount; ; eyecount=2; ; sprintf(string,"%s have %ld eyes.","Fish",eyecount); ; ; would produce "Fish have 2 eyes." in the string buffer. ; XDEF _sprintf XREF _AbsExecBase XREF _LVORawDoFmt _sprintf: ; ( ostring, format, {values} ) movem.l a2/a3/a6,-(sp) move.l 4*4(sp),a3 ;Get the output string pointer move.l 5*4(sp),a0 ;Get the FormatString pointer lea.l 6*4(sp),a1 ;Get the pointer to the DataStream lea.l stuffChar(pc),a2 move.l _AbsExecBase,a6 jsr _LVORawDoFmt(a6) movem.l (sp)+,a2/a3/a6 rts ``` -------------------------------- ### Assembly PutChProc for sprintf Example (m68k) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_036C.md The stuffChar function serves as the PutChProc callback for RawDoFmt in the sprintf example. It receives a character in D0 and the output buffer pointer in A3 (passed via PutChData) and writes the character to the buffer, incrementing the pointer. ```Assembly ;------ PutChProc function used by RawDoFmt ----------- stuffChar: move.b d0,(a3)+ ;Put data to output string rts ``` -------------------------------- ### CreateExtIO Function Synopsis (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/_0147.md Shows the function call syntax and the function prototype for CreateExtIO, which creates an IORequest structure. It takes a message port and the desired size of the IO request block. ```C ioReq = CreateExtIO(port,ioSize); ``` ```C struct IORequest *CreateExtIO(struct MsgPort *, ULONG); ``` -------------------------------- ### LINK Instruction Sample Syntax Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/link.md A sample usage of the M68k LINK instruction, using address register A6 and allocating 12 bytes of space on the stack with a negative displacement. ```Assembly LINK A6,#-12 ``` -------------------------------- ### Application Example of LEA for PC-Relative Addressing - M68k Assembly Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/lea.md Demonstrates how LEA can be used with PC-relative addressing to compute the address of a data table, facilitating position-independent code. The example then shows accessing and modifying data within the table using the calculated address. ```Assembly LEA (Table,PC),A0 ;Compute address of Table with respect to PC MOVE (A0),D1 ;Pick up the first item in the table . ;Do something with this item MOVE D1,(A0) ;Put it back in the table . . Table DS.B 100 ``` -------------------------------- ### Include Intuition Header Files in C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/_00D4.md Includes necessary header files for using Intuition screens and preferences structures and functions, providing access to definitions required for interacting with the Amiga graphics and user interface system. ```C #ifndef INTUITION_SCREENS_H #include #endif #ifndef INTUITION_PREFERENCES_H #include #endif ``` -------------------------------- ### Example Usage of RTR Instruction (Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/rtr.md This example demonstrates how to use the RTR instruction within a procedure (Proc1) to restore the Condition Code Register (CCR) after saving it on the stack at the beginning of the procedure. It shows the typical pattern of saving CCR before procedure body and restoring it upon return. ```assembly BSR Proc1 ;Call the procedure . . Proc1 MOVE.W SR,-(SP) ;Save old CCR on stack . . ;Body of procedure . RTR ;Return and restore CCR (not SR!) ``` -------------------------------- ### Setting Window Size Limits (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/WindowLimits.md This C code snippet shows the function signature and a typical usage pattern for `WindowLimits`. It illustrates how to call the function with a window pointer and the desired minimum and maximum width and height values, and how to check the boolean return value indicating success or failure. ```c Success = WindowLimits( Window, MinWidth, MinHeight, MaxWidth, D0 A0 D0 D1 D2 MaxHeight ) D3 BOOL WindowLimits( struct Window *, WORD, WORD, UWORD, UWORD ); ``` -------------------------------- ### InitGels Function Prototype (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/graphics/InitGels.md Provides the standard C language prototype for the InitGels function, detailing the required pointer types for the head VSprite, tail VSprite, and GelsInfo structure parameters. ```c void InitGels(struct VSprite *, struct VSprite *, struct GelsInfo *); ``` -------------------------------- ### Getting Soft Style Bits (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/graphics/AskSoftStyle.md This snippet shows the AmigaOS register usage (D0 for the return value and A1 for the RastPort pointer) and the C function prototype for AskSoftStyle. The function retrieves the algorithmically generated soft style bits from the provided RastPort structure. ```C enable = AskSoftStyle(rp) D0 A1 ULONG AskSoftStyle(struct RastPort *); ``` -------------------------------- ### Getting a Lock from File Handle (AmigaOS C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/dos/DupLockFromFH.md This snippet provides the synopsis and function signature for the AmigaOS `DupLockFromFH` function. It shows the register usage (D1 for input file handle, D0 for output lock) and the C function signature, indicating it takes and returns a `BPTR` (Base Pointer). ```C lock = DupLockFromFH(fh) D0 D1 BPTR DupLockFromFH(BPTR) ``` -------------------------------- ### OpenWindow Flags (System Gadgets) - C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/_00D4.md Defines preprocessor macros representing flags that can be passed to the `OpenWindow()` function to request the inclusion of standard system gadgets like sizing, dragging, depth arrangement, and close boxes in the window border. ```C /* --- Flags requested at OpenWindow() time by the application --------- */ #define WFLG_SIZEGADGET 0x00000001 /* include sizing system-gadget? */ #define WFLG_DRAGBAR 0x00000002 /* include dragging system-gadget? */ #define WFLG_DEPTHGADGET 0x00000004 /* include depth arrangement gadget? */ #define WFLG_CLOSEGADGET 0x00000008 /* include close-box system-gadget? */ ``` -------------------------------- ### WaitPkt Function Signature and Usage (C/Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/dos/WaitPkt.md This snippet shows the C function signature for `WaitPkt` and a conceptual usage example. The example `packet = WaitPkt() D0` indicates that the function returns a pointer to a `struct DosPacket`, which is typically returned in register D0 in the m68k assembly calling convention used by AmigaDOS. ```C packet = WaitPkt() D0 struct DosPacket *WaitPkt(void); ``` -------------------------------- ### PathPart Function Synopsis (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/dos/PathPart.md Synopsis of the PathPart function, showing its signature and register usage according to AmigaOS calling conventions. ```C fileptr = PathPart( path ) D0 D1 STRPTR PathPart( STRPTR ) ``` -------------------------------- ### Application Example: M68k DIVU Instruction Result Format - Assembly Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/instructions/divs_divu.md Illustrates the format of the result in the destination register after a M68k DIVU instruction, using the example of dividing D0 by D1. The 16-bit quotient is placed in the lower word (bits 0-15) of the destination register, and the 16-bit remainder is placed in the upper word (bits 16-31). ```assembly [D0(0:15)] ← [D0(0:31)]/[D1(0:15)] [D0(16:31)] ← remainder ``` -------------------------------- ### Function Prototype - AmigaOS Intuition C Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/ActivateWindow.md Provides the C language prototype for the ActivateWindow function, showing it takes a pointer to a struct Window and returns a LONG (in V36 and higher). ```c [LONG] ActivateWindow( struct Window * ); /* returns LONG in V36 and higher */ ``` -------------------------------- ### Synopsis - GetColorMap - C/Assembly Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_0445.md Shows the function signature in C and the register usage convention (input and output in d0) for the GetColorMap function. ```Assembly cm = GetColorMap( entries ) d0 d0 ``` ```C struct ColorMap *GetColorMap( ULONG); ``` -------------------------------- ### Macros for DosPacket Action Types (AmigaDOS) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_0078.md Defines constants representing the types of actions or commands sent in a `DosPacket`'s `dp_Type` field. These actions instruct the recipient (like a file system handler) on the operation to perform, such as startup, getting a block (obsolete), setting a map, dying, handling events, getting the current volume, locating an object, or renaming a disk. ```C /* Packet types */ #define ACTION_NIL 0 #define ACTION_STARTUP 0 #define ACTION_GET_BLOCK 2 /* OBSOLETE */ #define ACTION_SET_MAP 4 #define ACTION_DIE 5 #define ACTION_EVENT 6 #define ACTION_CURRENT_VOLUME 7 #define ACTION_LOCATE_OBJECT 8 #define ACTION_RENAME_DISK 9 ``` -------------------------------- ### Initialize a List structure (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/exec/_0161.md Initializes a standard List structure, preparing it for use as an empty list. The function takes a pointer to a List structure. ```c VOID NewList(struct List *); ``` -------------------------------- ### FindSegment Function Signature (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/dos/FindSegment.md This snippet shows the function signature for FindSegment, including the register usage convention (D0 for return, D1-D3 for parameters) and the C prototype. It finds a segment on the Dos resident list by name and type, starting after a specified segment or from the beginning if 'start' is NULL. It does not increment the segment's usage count or lock the list; locking with Forbid() is required before use. ```c segment = FindSegment(name, start, system) D0 D1 D2 D3 struct Segment *FindSegment(STRPTR, struct Segment *, LONG) ``` -------------------------------- ### Safely Closing Intuition Window with Shared Port - C Example Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/CloseWindow.md Example C code demonstrating how to safely close an AmigaOS Intuition window that shares a message port with other tasks. The CloseWindowSafely function uses StripIntuiMessages to remove and reply pending messages for the specific window before clearing its UserPort and calling CloseWindow, preventing issues with deallocated memory in the message queue. Requires includes like exec/types.h, exec/ports.h, and intuition/intuition.h. ```C /* CloseWindowSafely */ /* these functions close an Intuition window * that shares a port with other Intuition * windows or IPC customers. * * We are careful to set the UserPort to * null before closing, and to free * any messages that it might have been * sent. */ #include "exec/types.h" #include "exec/nodes.h" #include "exec/lists.h" #include "exec/ports.h" #include "intuition/intuition.h" CloseWindowSafely( win ) struct Window *win; { /* we forbid here to keep out of race conditions with Intuition */ Forbid(); /* send back any messages for this window * that have not yet been processed */ StripIntuiMessages( win->UserPort, win ); /* clear UserPort so Intuition will not free it */ win->UserPort = NULL; /* tell Intuition to stop sending more messages */ ModifyIDCMP( win, 0L ); /* turn multitasking back on */ Permit(); /* and really close the window */ CloseWindow( win ); } /* remove and reply all IntuiMessages on a port that * have been sent to a particular window * (note that we don't rely on the ln_Succ pointer * of a message after we have replied it) */ StripIntuiMessages( mp, win ) struct MsgPort *mp; struct Window *win; { struct IntuiMessage *msg; struct Node *succ; msg = (struct IntuiMessage *) mp->mp_MsgList.lh_Head; while( succ = msg->ExecMessage.mn_Node.ln_Succ ) { if( msg->IDCMPWindow == win ) { /* Intuition is about to free this message. * Make sure that we have politely sent it back. */ Remove( msg ); ReplyMsg( msg ); } msg = (struct IntuiMessage *) succ; } } ``` -------------------------------- ### Setting up an AmigaOS Hook (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/graphics/_012D.md A C function `SetupHook` demonstrating how to initialize a `struct Hook`. It takes a hook pointer, a pointer to the C function to be called (`c_function`), and user data, assigning them to the appropriate fields (`h_Entry`, `h_SubEntry`, `h_Data`). It assumes `hookEntry` is the address of the assembly stub. ```C SetupHook( hook, c_function, userdata ) struct Hook *hook; ULONG (*c_function)(); VOID *userdata; { ULONG (*hookEntry)(); hook->h_Entry = hookEntry; hook->h_SubEntry = c_function; hook->h_Data = userdata; } ``` -------------------------------- ### Setting Blitter Logic Function (M68k Assembly) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/hardware/DFF040_BLTCON0.md This snippet demonstrates how to write a 16-bit value to the BLTCON0 register using M68k assembly. The example value '$??f0' specifically targets the LF7-LF0 bits (bits 0-7) of BLTCON0, setting them to '$f0' (binary '11110000') as derived from the preceding table example. The '(a6)' indicates accessing the register via a base address, typically the custom chip base address. ```Assembly move.w #$??f0,BLTCON0(a6) ``` -------------------------------- ### Include Dependencies (C) Source: https://github.com/prb28/m68k-instructions-documentation/blob/master/libs/intuition/_00B8.md Includes necessary header files from the AmigaOS SDK for executive types, graphics functions, copper list definitions, graphics nodes, monitor specifications, and hardware custom registers. ```C #ifndef EXEC_TYPES_H #include #endif #ifndef GRAPHICS_GFX_H #include #endif #ifndef GRAPHICS_COPPER_H #include #endif #ifndef GRAPHICS_GFXNODES_H #include #endif #ifndef GRAPHICS_MONITOR_H #include #endif #ifndef HARDWARE_CUSTOM_H #include #endif ```