HomeAppendixXHDI - eXtended HardDisk Interface (Version 1.30)Index

16.9 Type definitions

In this hypertext there are references to the following data types:

AESVARS APPLRECORD ARHEADER BASEPAGE BCB
BCONMAP BITBLK BPB CD_DISC_INFO CD_TOC_ENTRY
CICON CICONBLK CPXINFO dev_descr DEVDRV
DISKINFO DITHER_MODE DOSTIME DOSVARS DRV_INFO
DSPBLOCK DTA EVNT fcookie FILEPTR
FILESYS fix31 FNTS_ITEM FONT_HDR fs_descr
GEM_MUPB GRECT HDFUNCS HNDL_OBJ ICONBLK
IOREC KBDVBASE KEYTAB LBOX_ITEM LINE
ltchars MAPTAB MCB MD MEDIA_SIZE
MEDIA_TYPE MENU META_DRVINFO META_INFO_1 META_INFO_2
META_HEADER MFDB MFORM MN_SET MOUSE
MPB MRETS mutimbuf OBJECT OHEADER
OSHEADER OVERPATCH PARMBLK PBDEF PD
PDLG_SUB PH ploadinfo POPINFO PRN_ENTRY
PRN_MODE PRN_TRAY PRN_SETTINGS PRN_SWITCH PUN_INFO
pxyarray RGB_LIST RSHDR SCANX SCREEN
SET_ITEM sgttyb SHELTAIL SLCT_ITEM SWINFO
tchars timeval timezone TEDINFO THREADINFO
USERBLK UTXT_FN winsize XAESMSG XATTR
XCPB XDO_INF XFNT_INFO XFSL_FILTER XSHW_COMMAND
XTED xkey      

16.9.1 AESVARS

typedef struct
{
     int32_t magic;                 /* Has to be 0x87654321       */
     void *membot;                  /* End of the AES variables   */
     void *aes_start;               /* Start address              */
     int32_t magic2;                /* Is 'MAGX'                  */
     int32_t date;                  /* Creation date              */
     void (*chgres)(int16_t res, int16_t txt);  /* Change resolution */
     int32_t (**shel_vector)(void); /* Resident desktop           */
     int8_t *aes_bootdrv;           /* Booting will be from here  */
     int16_t *vdi_device;           /* Driver used by AES         */
     void *reservd1;                /* Reserved                   */
     void *reservd2;                /* Reserved                   */
     void *reservd3;                /* Reserved                   */
     int16_t version;               /* Version (0x0201 is V2.1)   */
     int16_t release;               /* 0=alpha..3=release         */
} AESVARS;

Note: These variables are READ-ONLY!

The first three variables are also present under TOS, and can be obtained there from the operating system header. The vdi_device component is superfluous as of MagiC 2.0 as one gets the device number in a MultiTOS-compatible way with appl_getinfo (opcode 2). The routine for changing the resolution (chgres) expects in register d2 an optional Falcon-mode (as int16_t).

See also: MagiC's cookie   DOMagixAESVars

16.9.2 Archive header (ARHEADER)

typedef struct
{
  int8_t  a_fname[14];  /* Filename                  */
  int32_t a_modti;      /* Time of last access       */
  int8_t  a_userid;     /* Unused                    */
  int8_t  a_gid;        /* Unused                    */
  int16_t a_fimode;     /* File mode                 */
  int32_t a_fsize;      /* File length               */
  int16_t reserved;     /* Reserved                  */
} ARHEADER;

Note: An archive file in Digital Research format consists of a file- header, any number of files (each prefaced with an ARHEADER structure) as well as an end-identifier. The file-header here consists only of the WORD 0xff65, the end of the archive file is identified by the value 0x0000.

See also: OHEADER

16.9.3 Buffer Control Block (BCB)

typedef struct _bcb
{
  struct _bcb   *b_link;          /* Next BCB              */
  int16_t       b_negl;           /* Initialize to -1      */
  int16_t       b_private[5];     /* Unknown               */
  void          *b_buf;           /* Actual buffer         */
} BCB;

16.9.4 CPXINFO

typedef struct
{
    int16_t cdecl (*cpx_call)();
    void cdecl    (*cpx_draw)();
    void cdecl    (*cpx_wmove)();
    void cdecl    (*cpx_timer)();
    void cdecl    (*cpx_key)();
    void cdecl    (*cpx_button)();
    void cdecl    (*cpx_m1)();
    void cdecl    (*cpx_m2)();
    int16_t cdecl (*cpx_hook)();
    void cdecl    (*cpx_close)();
} CPXINFO;

See also: XCONTROL   cpx_init

16.9.5 FlpDrvInfo

This structure plays a role in connection with MagiC Mac, and is defined as follows:

typedef struct
{
   BOOLEAN  inserted;    /* True: disk is inserted and available */
                         /* to GEMDOS/BIOS functions             */
   BOOLEAN  highDensity; /* True: HD disk inserted, false: no or */
                         /* DD disk inserted                     */
   int16_t  res1;        /* Reserved                             */
   int32_t  res2;        /* Reserved                             */
} FlpDrvInfo;

See also: The MagiC Mac cookie

16.9.6 GEM_MUPB

This structure describes the 'GEM memory usage parameter block', which is defined as follows:

typdef struct
{
   int32_t gm_magic;  /* Magical value, has to be 0x87654321 */
   void *gm_end;      /* End of the memory required by GEM   */
   void *gm_init;     /* Start address of GEM                */
} GEM_MUPB;

See also: _sysbase   OSHEADER   System variables   System vectors

16.9.7 GRECT

typedef struct
{
   int16_t x;   /* X-coordinate */
   int16_t y;   /* Y-coordinate */
   int16_t w;   /* Width        */
   int16_t h;   /* Height       */
} GRECT;

See also: About the AES   GEM   About the VDI

16.9.8 HDFUNCS

typedef struct
{
    int32_t dma_begin ( void);
    int32_t dma_end   ( void );
    int32_t dma_wait  ( d0 = int32_t ticks_200hz );
    int32_t ncr_begin ( void );
    int32_t ncr_end   ( void );
    int32_t ncr_wait  ( d0 = int32_t ticks_200hz );
} HDFUNCS;

Note: Directly before the structure (2 bytes before) lies an int16_t, which specifies the table length in int32_ts (in this case 6). All 6 pointers lie in the system variables area and may be altered in case of need. The internal functions for the floppy drive also jump via the 6 pointers.
Important: The pointer hddrv_functions in the MagX cookie may not be altered.

See also: Background-DMA in MagiC

16.9.9 MacVersion

This structure plays a role in connection with MagiC Mac, and is defined as follows:

typedef struct /* 'vers' resource definition, see Inside Mac docs */
{
   int8_t vm;       /* First part of version number in BCD */
   int8_t vn;       /* Second and third part of version    */
                    /* number in BCD                       */
   int8_t  vt;      /* Development: 0x20, alpha: 0x40,     */
                    /* beta: 0x60, release: 0x80           */
   int8_t  vd;      /* Stage of pre-release version        */
   int16_t region;  /* Region code                         */
   int8_t  str[];   /* Two version strings                 */
} MacVersion;

See also: The MagiC Mac cookie

16.9.10 Memory-Control-Block (MCB) in MagiC

typedef struct
{
    int32_t mcb_magic;        /* 'ANDR' or 'KROM' (last)       */
    int32_t mcb_len;          /* Nett length                   */
    int32_t mcb_owner;        /* Pointer to PD structure       */
    int32_t mcb_prev;         /* Previous block, or NULL       */
    int8_t mcb_data[0];
} MCB;

Note: The component mcb_magic has the value 'KROM' if no futher MCB follows, else the value 'ANDR'. In the latter case the next MCB lies mcb_len bytes behind the currrent MCB. The list is chained backwards with mcb_prev which considerably speeds up many operations.

With all memory operations the component mcb_magic is always checked, and if an error is found the system is halted immediately. For a halt due to a memory error the address of the faulty MCB as well as the data (4 LONGwords) are output. Subsequently one is asked on which

drive one would like a core dump to be saved. If one specifies a valid drive, then the whole ST memory from 0 to phystop is written to the root directory of the specified drive, and is assigned the

name '_sys_'. The file, depending on the ST model, can be up to 4 or even 16 MB long, of course.

Memory-resident programs (terminating themselves with Ptermres) now work - unlike earlier - in a way that the blocks are not released, all MCBs remain intact and continue to be used (each time one clicks in the menu-bar the free memory is output, for which the whole list is run through once and during this all MCBs are checked). Those who wish to do so can therefore release memory-resident programs (or also parts of them) subsequently.

See also: GEMDOS   MagiC   MD   Memory management

16.9.11 Memory Descriptor (MD) in TOS

typedef struct md
{
    struct md *m_link;      /* Pointer to next MD         */
    int32_t      m_start;   /* Start address of the block */
    int32_t      m_length;  /* Length of the block        */
    BASEPAGE  *m_own;       /* Pointer to the basepage    */
} MD;

Note: The component m_own here points to the basepage of the process to which the memory block belongs.

These structures are administered in the internal memory management of TOS (but not of MagiC!). These descriptors, as far as they are used, hang in three memory lists, namely for free blocks, occupied blocks and for the next block to be occupied (mem_rover). With the mem_rover concept one attempts to achieve that consecutive Malloc calls reserve consecutive memory if possible (this has been described as an error already elsewhere). This is intended to reduce memory segmentation.

This idea is unusable if several programs are running simultaneously and call Mallocs alternately, however. The concept implemented by Atari has the advantage that it is not sensitive to programs that run amuck, since the MDs lie is system memory, far away from user memory. A known disadvantage of the described concept is that only a very restricted number of Malloc calls are possible, since every call swallows an MD of the limited system memory; this is also massively burdened by opened folders and files. A further disadvantage of the TOS memory management: If a program overspills a memory block, i.e. writes past its end, then this generally passes completely unnoticed.

Specially in multitasking systems the danger of an overwritten memory block is very much higher than in TOS. Furthermore, the number of memory blocks required, as well as those for folders (each program has its own files and standard directories) is appreciably higher. For these resons MagiC has a completely different concept; in that there is only one memory list whose pointers point to the first MCB.

See also: About the GEMDOS   MCB   MPB   Memory management   themd

16.9.12 MRETS

typedef struct
{
    int16_t x;
    int16_t y;
    int16_t buttons;
    int16_t kstate;
} MRETS;

See also: cpx_button   cpx_m1   cpx_m2   XCONTROL

16.9.13 OHEADER

This structure describes the header of an object file in Digital Research format:

typedef struct
{
   int16_t magic;         /* Magical value: 0x601a      */
   int32_t tsize;         /* Size of the TEXT segment   */
   int32_t dsize;         /* Size of the DATA segment   */
   int32_t bsize;         /* Size of the BSS            */
   int32_t ssize;         /* Size of the symbol table   */
   int8_t reserved[10];   /* Reserved, set to zero      */
} OHEADER;

See also: ARHEADER   BASEPAGE

16.9.14 OSHEADER

typedef struct _osheader
{
    uint16_t    os_entry;       /* BRAnch instruction to Reset-handler  */
    uint16_t    os_version;     /* TOS version number                   */
    void       *reseth;         /* Pointer to Reset-handler             */
    struct _osheader *os_beg;   /* Base address of the operating system */
    void       *os_end;         /* First byte not used by the OS        */
    int32_t     os_rsvl;        /* Reserved                             */
    GEM_MUPB   *os_magic;       /* GEM memory-usage parameter block     */
    int32_t     os_date;        /* TOS date (English !) in BCD format   */
    uint16_t    os_conf;        /* Various configuration bits           */
    uint16_t    os_dosdate;     /* TOS date in GEMDOS format            */

    /* The following components are available only as of TOS Version
       1.02 (Blitter-TOS)               */
    int8_t    **p_root;         /* Base address of the GEMDOS pool      */
    int8_t    **pkbshift;       /* Pointer to BIOS Kbshift variable
                                   (for TOS 1.00 see Kbshift)           */
    BASEPAGE  **p_run;          /* Address of the variables containing
                                   a pointer to the current GEMDOS
                                   process.                             */
    int8_t     *p_rsv2;         /* Reserved                             */
                                /* If EmuTOS is present, then 'ETOS'    */
} OSHEADER;

The structure also appears under the name SYSHDR.

os_conf The component os_conf contains the so-called NTSC/PAL flag in its lowest bit; if this bit is set, then the machine has a PAL video system, if cleared NTSC. The remaining bits contain a country identifier, which can serve to denote the language used for menus etc. for instance. The folowing assignments apply:

Value Country
0 to 126 see the define by the _AKP cookie
127 All countries are supported.


Warning: To obtain the language in use, one should fall back not to the OSHEADER if possible, but use the _AKP cookie or the function appl_getinfo (opcode 3).
p_root With older TOS versions the address of p_root is 0x56FA.
p_run
BASEPAGE **GetRun (void)
{
  int32_t savessp = Super (0L);
  OSHEADER *O = *((OSHEADER **)(0x4f2L);
  Super ((void *) savessp );

  O = O->os_beg;   /* wegen eines Fehlers in alter AHDI-Version */

  if (O->os_version < 0x102)
  {
    if ((O->os_conf >> 1) == 4)      /* PAL-Modus wegshiften */
      return ((BASEPAGE **)0x873c);  /* Spanisches TOS 1.0   */
    else
      return ((BASEPAGE **)0x602c);
  }
  else
    return O->p_run;
}

See also: Kbshift   _sysbase   System variables   System vectors

16.9.15 PrintDesc

This structure plays a role in connection with MagiC Mac, and is defined as follows:

typedef struct
{
    THPrint     printHdl;       /* Printer-configuration for NVDI */
    PrSetupProc doPrintSetup;   /* ditto                          */
    VoidProcPtr saveSetup;      /* ditto                          */
    int32_t     reserved[7];    /* Reserved                       */
} PrintDesc;

See also: The MagiC Mac cookie

16.9.16 RGB_LIST

typedef struct
{
    uint16_t red;     /* Red proportion in parts per thousand   */
    uint16_t green;   /* Green proportion in parts per thousand */
    uint16_t blue;    /* Blue proportion in parts per thousand  */
} RGB_LIST;

See also: XIMG format

16.9.17 THREADINFO

typedef struct
{
   int32_t cdecl (*proc)(void *par);
   void          *user_stack;
   uint32_t      stacksize;
   int16_t       mode;
   int32_t       res1;
} THREADINFO;

Note: If the component user_stack is NULL, then the system will create the stack itself. When the thread terminates, the system will release the stack again automatically. The component stacksize must always be specified so that the system can set the stack pointer of the thread to the end of the stack. The supervisior-stack is set by the operating system, so that its size cannot be influenced.

The components mode and res1 are reserved for future purposes, so they should be set to the value 0 or 0L. In Solaris 2.x, for instance, one can arrest the thread up to the final start with them. The started thread executes the function proc, which is passed as a parameter to the component par (on the stack). The CPU registers d0-d2 and a0-a2 may be altered by the function.

See also: Threads in MagiC   shel_write   Sample code

16.9.18 XCPB

typedef struct
{
    int16_t       handle;
    int16_t       booting;
    int16_t       reserved;
    int16_t       SkipRshFix;
    void          *reserve1;
    void          *reserve2;
    void cdecl    (*rsh_fix)      ( int num_objs, int num_frstr, int num_frimg,
                                    int num_tree, OBJECT *rs_object,
                                    TEDINFO *rs_tedinfo, char *rs_strings[],
                                    ICONBLK *rs_iconblk, BITBLK *rs_bitblk,
                                    long *rs_frstr, long *rs_frimg, long *rs_trindex,
                                    struct foobar *rs_imdope );
    void cdecl    (*rsh_obfix)    ( OBJECT *tree, int curob );
    int16_t cdecl (*Popup)        ( char *items[], int num_items, int default_item,
                                    int font_size, GRECT *button, GRECT *world );
    void cdecl    (*Sl_size)      ( OBJECT *tree, int base, int slider, int num_items,
                                    int visible, int direction, int min_size );
    void cdecl    (*Sl_x)         ( OBJECT *tree, int base, int slider, int value,
                                    int num_min, int num_max, void (*foo)() );
    void cdecl    (*Sl_y)         ( OBJECT *tree, int base, int slider,  int value,
                                    int num_min, int num_max, void (*foo)() );
    void cdecl    (*Sl_arrow)     ( OBJECT *tree, int base, int slider, int obj,
                                    int inc, int min, int max, int *numvar,
                                    int direction, void (*foo)() );
    void cdecl    (*Sl_dragx)     ( OBJECT *tree, int base, int slider,
                                    int min, int max, int *numvar, void (*foo)() );
    void cdecl    (*Sl_dragy)     ( OBJECT *tree, int base, int slider,
                                    int min, int max, int *numvar, void (*foo)() );
    int16_t cdecl (*Xform_do)     ( OBJECT *tree, int start_field, int puntmsg[] );
    GRECT * cdecl (*GetFirstRect) ( GRECT *prect );
    GRECT * cdecl (*GetNextRect)  ( void );
    void cdecl    (*Set_Evnt_Mask)( int mask, MOBLK *m1, MOBLK *m2, long time );
    int16_t cdecl (*XGen_Alert)   ( int id );
    int16_t cdecl (*CPX_Save)     ( void *ptr, long num );
    void * cdecl  (*Get_Buffer)   ( void );
    int16_t cdecl (*getcookie)    ( long cookie, long *p_value );
    int16_t       Country_Code;
    void cdecl    (*MFsave)       ( int saveit, MFORM *mf );
} XCPB;

See also: cpx_init   XCONTROL


HomeAppendixXHDI - eXtended HardDisk Interface (Version 1.30)Index