-

LIBRARIES PUBLIC DOCUMENT BANKING LIBRARY

From HI-TECH C for CP/M Fan WIKI(EN)
Jump to: navigation, search

Preface

Hitech-C Banking Library for HI-TECH C is a library for HI-TECH C Compiler. It provides programming environment for memory unlimited and large sized DOS 2 program by activating function to assign MSX-DOS 2 controllable memory segments. This library contains functions for interruption, slot controlling, key input view graphics and so on other than basic banking.

Development environment

OS: Windows XP or higher

CP/M Emulator: CP/M EXEcutor (http://hp.vector.co.jp/authors/VA000084/)

C Compiler / Assembler: HI-TECH C v3.09 (Public tool for CP/M)

MAKE Tool: GNU Make for Windows v3.81 (http://www.gnu.org/software/make/)

Banking Librariy and Banking Build Tools: This package


In addition to that above, IDE for source project management/building is useful. I use Code::Blocks. This is is open source IDE.

HI-TECH C does not support subdirectory because this is originally for CP/M. I build using mapping function from directory to drive on CP/M EXEcutor. If you use Linux or other OS than Windows, you need mapping function from directory to drive on CP/M emulator.

FYI, all Bank Building Tools which I made are designed for CP/M execution.


Execution environment

This library requires MSX2 with more than 256k main RAM and MSX-DOS2.

Banking unit is 32KB each, then 32KB free memory is required other than TPA memory of DOS2 if you make program for minimum banking size.

(DOS2 system 32KB + TPA 64KB + bank 32KB = 128KB)

FYI, MSX turboR uses 64KB memory as shadow area of the BIOS and does not have so much free memory (3 banks = 96KB available)


Memory Map

0000H-00FFH : DOS System Calls

0100H-7FFFH : Program Area Bank#0 <-> Program Area Banks#0....

8000H-83FFH : Banks and Interrupt routines

8400H-8FFFH : Banking Stacks

9000H-FFFFH :

Internal Buffers Shared Heaps, Stacks and MSX Work Areas

Bank #0 has program loader and user code is written from bank#1. You can append codes to remained RAM of bank#0.

Main() function and ISR(interrupt service routine) are locatable everywhere because this is not limited by location of the bank. LIB link is done in every bank separately.

Different library can be linked in each bank. For example: bank #1 links to LIBMSX2.LIB and bank #2 links to LIBMSX2.LIB e. g.

These are the points to be noticed below.

Programs in each bank cannot be exceeded 32KB including TEXT, DATA and BSS. Don't assign memory dynamically to 8000H and higher by malloc() etc. in each banks inside.

Data passing can be done via shared heap memory (using bl_malloc and related functions). Bank calling can be done via banking helper routine while building. These are not to be in consideration.

Build

Installation of develop environment

Copy GNU Make where path is reachable on Windows box. FYI, open command window and type "path" and enter to check path reachable directory.

Installed MAKE is used if gcc tools like MinGW is installed.

All contents of the packages, such as CPM emulator, bank building tools and HI-TECH C tools should be previously put into one directry. I've copied these files into CPMEMU_HI-TECH C of archive file.

This is contents of my C:\Emul\CPMEMU_HI-TECH_C directory.

C:\Emul\CPMEMU_HI-TECH_C
BLCRT.C CPM.EXE MSXBIOS.H LIBG.LIB
BLGRPFNT.C ASSERT.H MSXIO.H CRT.O
BLGRPINI.C BANKCALL.H SETJMP.H CRT2.O
BLSRC.CFG BLGRP.H SIGNAL.H
BLCALLER.COM BLGRPDAT.H STAT.H
BLEXTREF.COM BLSTDLIB.H STDARG.H
BLMERGE.COM BLTYPE.H STDDEF.H
BLMKRULE.COM CONIO.H STDIO.H
CGEN.COM CPM.H STDLIB.H
CPP.COM CPM_ORG.H STRING.H
CREF.COM CPUMODE.H SYS.H
DEBUG.COM CTYPE.H TIME.H
GEN80.COM EXEC.H LIBC.LIB
LIBR.COM FLOAT.H LIBCGEN.LIB
LINK.COM GLIB.H LIBCMSX.LIB
OBJTOHEX.COM HITECH.H LIBCMSX2.LIB
OPTIM.COM KEYIO.H LIBF.LIB
P1.COM LIMITS.H LIBFGEN.LIB
POPCOM.COM MATH.H LIBFMSX.LIB
ZAS.COM MSXBDOS.H LIBFMSX2.LIB

Hello MSX!

This section explains how to build HELLO program as a sample of banking program.These are the files in HELLO program directory. This is a simple code, so it can be used as a default template for new project.

D:\My_Work\[MSX]\BANKED_APP\HELLO
MAKEFILE
_BUILD.BAT
MAIN.X
HELLO.CFG

Makefile Settings

This MAKEFILE is used by all banking programs commonly. You need modify Only these points below. Set directory path in valuable CPMDIR, where development tools were installed in chapter 2.1 of this document.

HELLO\MAKEFILE

###
#    HI-TECH C package path
#
CPMDIR       := C:\Emul\CPMEMU_HI-TECH_C

CFG Settings

File name of CFG file, like HELLO.CFG, determines program name of execution file after build like.

This is contents of HELLO file.


target  := $(CFG)

cflag +=           \


src-bank00 +=      \


lib-bank00 +=      \
    A:LIBCMSX2.LIB \


src-bank01 +=      \
    MAIN.C         \


lib-bank01 +=      \
    A:LIBCMSX2.LIB \

Target setting is not to be modified.

Common options for compile can be appended as cflag. FYI, default options are stored in cflag in MAKEFILE.

Each bank should have src-bankXX and lib-bankXX. These are the list of source and library files. Only MAIN.C is added in HELLO program.

You can see 2 banks, bank00 and bank 01 in lists above. It shows that loader of bank file (*.OVL files) are basically contained and MAIN.C belongs to bank01.

Each lib-bankXX basically links LIBCMSX2.LIB. Link LIBFMSX2.LIB if you use float point library.


These are the points to be noticed below.

Each source code generates OBJ files via compiler and assembler. After that these files generate binary codes of each banks. If there are many source files or too long named files, parameter on CP/M exceeds limits and error occurs.

If you need more than 5 files to be added in one bank, I recommend to change file names to as short as possible. Example: EX.C、E1.C、E2.C etc.


main()

Main() function of HELLO program exists in MAIN.C. It is the simple codes to output "Hello MSX!" and returns to DOS2.

/***********************************************************

	HELLO (Banking Library Demo)

***********************************************************/

#include <stdio.h>
#include <string.h>
#include <sys.h>
#include <msxio.h>
#include <msxbdos.h>
#include <bltype.h>
#include <blstdlib.h>

int main(int argc, char* argv[])
{
	printf("Hello MSX!\n");

	return 0;
}

;


It is not different from ordinary codes of C language, except that #include is needed when you use banking application.

#include<bltype.h>
#include<blstdlib.h>

_BUILD.BAT

This is the final batch file which is used to build on command window. Output messages are saved as _BUILD.TXT file. When error occured while building, refer this file.

These are examples for building/cleaning of HELLO program.

Build:_BUILD HELLO Clean:_BUILD HELLO CLEAN


Generated Files

When you build, directory which has same name as program (also same as CFG file) is genarated. Execution file (*.COM) and bank file (*.OVL) are generated inside it.

These are the contents of OUTPUT directory and source files. Bank file of HELLO program (HELLO.OVL) uses whole 1 bank and ocupies 32KB.

D:\My_Work\[MSX]\_BANKED_APP\HELLO
HELLO
MAKEFILE
B00.AS
B01.AS
HELLO.B01
_BUILD.BAT
MAIN.C
HELLO.CFG
B00.LST
B01.LST
B00.MAP
B01.MAP
HELLO.MK
B00.O
B01.O
BLCRT.OBJ
MAIN.OBJ
EXTERN.REF
_BUILD.TXT
D:\My_Work\[MSX]\_BANKED_APP\HELLO\HELLO
HELLO.COM
HELLO.OVL

This is result of direct execution on MSX emulator.

A:\>HELLO
Hello MSX!
 Volume in drive A: has no name
 Directory of A:\

HELLO    COM      7552 11-03-26 2:00a
HELLO    OVL     32768 11-03-26 2:00a

39K in 2 files 40K free
A:\>


Symbol List

BLTYPE.H

It contains definitions of data types which Banking Library requires.

int8_t, int16_t, int32_t,
uint_8_t, uint16_t, uint32_t


BLSTDLIB.H

Basic valuables and functions which banking application uses.

Bank Number

extern int16_t bl_bank
We can know bank number of current executed code from this (don't change value). Bank number matches numbers written in CFG setting file.

TSR

void bl_tsr_on(void)
Enables TSR function. Bank codes(*.OVL) of TSR are remained resident on memory, if program ended. DATA and BSS are not initialized when restart the program, because resident banking codes are executed.
If you want to remain executed program, run bigger program or execute high-frequently(like DOS shell) it is convienience because it does not read disk again.


Shared Heap

Functions for managing shared heap memory. Shared heap memory is assigned at after 9400H.

void *bl_calloc(size_t num, size_t size)
Function corresponds to calloc().
void bl_free(void *ptr)
Function corresponds to free().
void *bl_malloc(size_t size)
Function corresponds to malloc().
void *bl_realloc(void *ptr, size_t size)
Function corresponds to realloc().

Interruption

All of PAGEs basically select RAM on MSX-DOS2 environment. Vector interruption of 0038H are processed on workarea of PAGE3 and PAGE0 are switched to MAIN BIOS slot for processing ISR by existed MSX BIOS. When it is processed, callbacks of user ISR can not be directly executed (because it exists on PAGE0,1) but there are not memory limitation for processing ISR bank switching from main ISRs of Banking Library existed at PAGE2. Thus ISR can be written as a ordinary functions.

void bl_enable_bios_timi(void)
TIMI internal routine - ISR of MAIN BIOS are enabled and can be used. It must be enabled when you use key input of stdio, joysticks and playing MUSICs. FYI, TIMI of BIOS basically stays ON.
void bl_disable_bios_timi(void)
TIMI internal routine - ISR of MAIN BIOS are disabled and can not be used. Disable this when key input processing for games separately implemented or when if you don't need TIMI internal routine for making interrupt speed faster.
int16_t bl_request_irq(uint8_t irq, uint16_t handler)
Requests IRQ and regist interrupt ISR. MSX uses fixed interrupt mode with 0038H and doesn't use vector mode interruption of Z80.
FYI, HBLK ISR is not executed with every H_BLANK from VDP but with a H_BLANK which is set VDP line interrupt register(R19).
int16_t bl_free_irq(uint8_t irq)
Remove ISR from this interruption.
void bl_enable_irq(uint8_t irq)
Enable this IRQ.
void bl_disable_irq(uint8_t irq)
Disable this IRQ.

Frame Rate Control

void bl_set_frame_rate(uint8_t rate)
Sets frequency of bl_wait_frame_rate() - V_BLANK wait function. When it is needed under V sync 60Hz mode, set 60/rate times in every second.
void bl_wait_frame_rate(void)
Waits until V_BLANK rate of VDP has come, which set by bl_set_frame_rate() function. FYI,
FYI, this function doesn't start to count V_BLANK when it is called but refers V_BLANK counted in main ISR of Banking Library

Slots

Transfer memory blocks or read/write addressed of appropriate slots by changing slot of PAGE1(4000H-7FFFH).

uint8_t bl_read_slot(uint8_t slot, uint8_t *addr)
Reads memory address of appropriate slot. Slot number is same as format of RDSLT of BIOS (BIT7: Select expantion slot, BIT3,2, Expanded slot number, BIT1,0: Basic slot number).
void bl_write_slot(uint8_t slot, uint8_t *addr, uint8_t data)
Write to mamory of appropriate address.
void bl_copy_to_slot(uint8_t slot, uint8_t *dest, uint8_t *src, uint16_t count)
Transfer memory by changing slot of PAGE1.
void bl_copy_from_slot(uint8_t slot, uint8_t *src, uint8_t *dest, uint16_t count)
Transfer memory by changing slot of PAGE1. FYI, it works same as bl_copy_to_slot function except only order of parameters are different.
void bl_select_page1_slot(uint8_t slot)
Disable interruption by changing slot of PAGE1.
void bl_restore_page1_slot(void)
Enable interruption by recovering slot of PAGE1 into former program memory slot.

Execution of 16KB ROM Images

void bl_execute_rom(uint16_t addr)
Execute 16KB ROM image. ROM image is loaded into PAGE1, by transferring 16KB which starts from this address. After that, PAGE0 is changed to slot of MAIN BIOS and INIT routine of ROM image is executed. This can be used for 128KB ROM game for MSX1.

Demo Programs

HELLO

This is the program introduced at chapter 2. This is consisted from simple main() function which uses one extended bank.

Demo

This is main demo program of this Banking Library. It is example for basic disc managiment functions of DOS and banking, interrution processing.

MAIN.C
It has text menu and each sub functions are located in different bank. Prpgrammers can write codes freely if each functions located within a bank memory(32K) and can refer special settings for function calling????
DOS.C
This is example for using environmental values of DOS2 and showing file size by searching appropriate file name.
INTR.C
IT is easy sample for using external and V_BLANK interruption. It works with key proccessing routine of MAIN BIOS here.
INTR_TR.C
It is sample for faster interruption of turboR. It uses H_BLANK interrution of VDP 16 times within 1 frame(1/60 sec.). It enables pannning display effect by setting ADJUST register quickly. FYI, ISR is executed at about every 825 micro sec.(0.000825 sec.).
KEYIO.C
It is demo for key input processing.
GRAPIC.C
It is example for using GLIB, public graphic library. FYI, GLIB calls internal MSX BIOS routines, not implemented by native code.
GRP_FONT.C
It is example for displaying 8x16 English fonts and 16x16 Hangeul fonts on graphics mode of interlaced screen 7 (512x424). It contains complete codes converting conbind form from complete form and draws font faster by in-line assembler of HI-TECH C.
EXEROM.C
It is example for directly execute Konami's 16KB ROM game "King's Valley" from the program.


MPXPS

This program is for playing MP3 with MPX cartridge made by Junseong Kim. You can refer codes for CPU switching to Z80 3.58MHz on turboR, changing slot PAGE1, finding MPX cartridge, processing memory map I/O of MPX.

There are 2 ways of transferring data to MPX cartridge, bl_select_page1_slot() with memcpy() and bl_copy_to_slot() in it.

Thanks to

Caution: I don't provide 100% of operation garantee for Banking Library and Build Tools which I make. I do not take any responsibility by using this library, so be carefully use it.


Opinion: Send email to sharksym[at]hitel.net if you have questions, proposal and requests. FYI, you can get information on my blog http://sharksym.egloos.com/ as well.

Appreciation: Many thanks to all members of "MSX Heaven" group, testers and many of supporter of Banking Library.

History

2011.3.26

Added interruption and VDP routine into PDF manual

2010.10.09

Bug fix for analyzing build tool

2010.08.06

Released 1st version.