SuperH-based fx calculators
fx legacy: MCS

Beware of MCS inconsistencies:
When inserting or deleting MCS-objects or increasing the size of an existing MCS-item, it is important to use handle-based MCS-syscalls. Otherwise process-switching (MENU-key) could lead to an inconsistent main memory. F. i. e-ACT can get confused, if it cannot detect changes applied to the main memory by another process.
A safe way seems to be the use of syscalls, the BfileMainMemory-functions rely on.

MCS syscalls

To understand MCS syscalls, it could be useful to know the main memory's structure.
Some MCS syscalls operate on MCS-handles.

0x0363: int MCS_CreateDirectory( unsigned char*dir, char*dirno );
Creates an entry dir in the MCS directory.
Returns the number of the created directory in *dirno.
Returns 0, if no error occurs.
Returns 0xF0, if dir==0 or the length of *dir==0.
Returns 0x42, if the directory already exists.
Returns 0x43, if the directory space is exhausted.

0x0364: int MCS_WriteItem( unsigned char*dir, unsigned char*item, short itemtype, int data_length, int buffer );
Creates or overwrites item dir.item of length data_len into the MCS.
item data are initialized with buffer.
itemtype is used to set dir.item-member flags[0].
Returns error 0x40, if dir does not exist.
Returns error 0x35, if dir.item exists and if bit 6 of dir.item-member flags[0] is set (readonly-flag; before changed by the actual function call!).
Returns error 0x32, if dir.item-member's flags[1] bit 0 is 1.
Returns error 0x34, if dir.item-member's flags[1] bit 1 or 2 is 1.
Returns error 0x10, if data_length is not 4-aligned.
Returns error 0x11, if MCS-capacity is exhausted.
Returns 0, if no error occurs.
This is a 5-parameter syscall!

0x0366: int MCS_DeleteDirectory( unsigned char*dir );
Deletes the MCS directory dir.
returns 0, if no error occurs.
Returns 0xF0, if dir==0 or the length of *dir==0.
Returns 0x40, if dir not found.
Returns 0x45, if item-count is not zero. If items are present, use 0x086F beforehand.
Returns 0x46, if *dir=="@APLWORK" or "main".
Returns 0x46, if dirno > 0x66.
Returns 0x47, if dir's flags[1] bit 0 is 1.

0x0367: int MCS_DeleteItem( unsigned char*dir, unsigned char*item );
Deletes dir.item.
Returns 0, if successful.
Returns 0xF0, if either dir or item==0 or the length of *dir or *item ==0.
Returns 0x40, if dir not found.
Returns 0x30, if item not found.
Returns 0x32, if item's flags[1] bit 0 is 1.
Returns 0x34, if item's flags[1] bit 1 or 2 is 1.

0x0368: int MCS_GetState( int*maxspace, int*currentload, int*remainingspace );
Returns max. available main memory in *maxspace.
Returns current main memory load in *currentload.
Returns currently availabe main memory in *remainingspace.
Returns 0.

0x0369: int MCS_GetSystemDirectoryInfo( unsigned char*dir, unsigned int*pdir, char*dirno );
Returns some information concerning the main-directory.
name: usually "main".
pdir: usually 0x88030A10
dirno:usually 2.

0x0370: int MCS_RenameItem( unsigned char*srcdir, unsigned char*srcitem, unsigned char*tgtdir, int tgtitem );
Renames (moves) srcdir.srcitem to tgtdir.tgtitem.
This function first copies srcitem to tgtitem and than deletes srcitem. Hence, it needs temporary MCS-space of the size of the object to be renamed. Else it returns memory full error 0x5F. That is a considerable disadvantage.
Returns 0x40, if srcdir or tgtdir does not exist.
Returns 0x32, if srcitem's flags[1] bit 0 is 1.
Returns 0x34, if srcitem's flags[1] bit 1 or 2 is 1.
Returns 0x5F, memory full.

0x0371: int MCS_OverwriteData( unsigned char*dir, unsigned char*item, int write_offset, int bytes_to_write, void*buffer );
Writes bytes_to_write bytes of buffer to dir.item.
write_offset defines where to start the write inside dir.item's data area.
returns 0x13, when the number of bytes to write exceeds the item's actual data length.
returns 0x14, when the bytes_to_write plus write_offset exceeds the item's actual data block end.
returns 0, if no error occurred.
This is a 5-parameter syscall!

0x0372: int MCS_GetItemData( unsigned char*dir, unsigned char*item, int offset, int bytes_to_read, void*buffer );
Reads bytes_to_read bytes from dir.item to *buffer.
offset defines where to start the read inside dir.item's data area.
Returns 0, if no error occurred.
This is a 5-parameter syscall!

0x0373: int MCS_RenameDirectory( unsigned char*oldname, unsigned char*newname );
Renames MCS directory entry oldname to newname.
Returns 0, if no error occurs.

0x0375: int MCS_SearchDirectory( unsigned char*dir, TMainMemoryDirectoryEntry*pdir, char*dirno );
Searches dir in the MCS directory.
Returns the pointer to the directory entry in *pdir.
Returns the number of the directory entry in *dirno.
Returns 0, if no error occurs.
Returns 0xF0, if dir==0 or the length of *dir==0.
Returns 0x40, if dir not found.

0x0376: int MCS_SearchDirectoryItem( unsigned char*dir, unsigned char*item, char*flags_0, TDirectoryItem*item_ptr, int*data_ptr, int*data_length );
Tries to locate item in the MCS directory dir and if successful, retrieves some information of item.
Returns dir.item-member flags[0] in *flags_0, the meaning of which is unknown yet (except bit 6, see 0x364).
Returns the pointer to the item in *item_ptr.
Returns the pointer to the data in *data_ptr.
Returns the length of the data in *data_length.
Returns 0, if no error occurs.
Returns 0x30, if item not found.
This is a 6-parameter syscall!
Example: sys0376( "system", "ABC", ... ) investigates the properties of the BASIC-program "ABC".

0x037C: int MCS_GetFirstDataPointerByDirno( char*dirno, void*pdata );
Retrieves the first(!) data pointer of MCS directory (by dirno) in *pdata.
Returns the same value.
It does not check the allowed range of dirno! It steps in an exception-trap if dirno is outside of 1..0x93.
This function may be useful for directories with one data-item (f. i. "@RUNMAT"/"RECALL", the RUN.MAT history).

0x037D: int MCS_GetDirectoryEntryByNumber( char dirno, TMainMemoryDirectoryEntry*pdir );
Retrieves the MCS directory entry address in *pdir by dirno.
Returns 0, if no error occurs.
Returns 0x44, if dirno is outside of the allowed range 1..0x93.
The function allows to build a MCS-findfirst/findnext functionality.

0x037E: int MCS_SearchItem( unsigned char*item, TMainMemoryDirectoryEntry*pdir, unsigned short*itemno );
Searches item in the MCS directory pointed at by pdir.
item has to be zero padded to 8 chars!
Returns the number of the directory item in *itemno.
The *itemno range starts at zero.
returns 0, if no error occurs.

0x037F: int MCS_str8cpy( unsigned char*source, unsigned char*target, int mode );
Copies max. 8 chars of source to target (t. i. strncpy( target, source, 8 ) )
With mode = 0, target is converted to upper case.
With mode = 1, target is converted to lower case.
With mode = 2, target is not converted.
Returns 0, if no error occurs.
Returns 0xF0, if the source length is zero.
Is often used in connection with MCS-functions.

0x0380: void MCS_GetDirectoryEntryAddress( void*directory_entry_address );
directory_entry_address receives the start of MCS RAM directory.

0x0381: void MCS_GetCurrentBottomAddress( void*current_bottom_address );
current_bottom_address receives the MCS RAM bottom (0x88030000..0x8803FFFF).

0x0383: int MCS_GetCapa( int*current_bottom );
current_bottom receives the current MCS RAM bottom.
returns Main Memory capacity

0x0392: int MCS_GetMainMemoryStart( void );
returns the MainMemoryStart-address.

A second set of syscalls is documented in MCS-handles.

(18.03.2011 16:14:42)