Changes between Initial Version and Version 1 of BuildInstructions

Timestamp:

Jul 8, 2021, 12:12:16 AM (3 years ago)

Author:

Krister Nordvall

Comment:

Added BuildInstructions

BuildInstructions

@@ +1 @@
+= Introduction =
+
+This is a small tutorial on how to build XTIDE Universal BIOS on Windows.
+
+= Programs needed =
+
+  * [https://tortoisesvn.net/ TortoiseSVN] (or any SVN client)
+  * [https://jmeubank.github.io/tdm-gcc/ MinGW] (only mingw32-make.exe is needed)
+  * [https://www.nasm.us/ NASM]
+  * [https://upx.github.io/ UPX] (optional)
+  * [https://strawberryperl.com/ Strawperry Perl] (optional)
+
+----
+= Install TortoiseSVN =
+
+TortoiseSVN is a subversion client that is very easy to use since it integrates nicely with Windows Explorer. It is used to download XTIDE Universal BIOS sources. Anyone can download sources from the repository but you must be a project member to commit changes back to it.
+
+[https://tortoisesvn.net/downloads.html Download and install TortoiseSVN]. You can use the default settings that the installer suggests.
+
+== Downloading sources ==
+First you need to create the folder where you want to download the sources. In this example we will create a folder named XUB in D:\Projects.
+
+Once the folder is created, right click on it and select "SVN Checkout..." from the menu.
+[[Image(TortoiseMenu.png)]]
+
+URL for the repository is https://www.xtideuniversalbios.org/svn/xtideuniversalbios/trunk. There is no need to alter other settings so just click OK. You will now download all sources from the XTIDE Universal BIOS project.
+[[Image(SvnCheckout.png)]]
+
+== Updating sources ==
+
+If you have already done all of the above and at a later time want to get the latest revision of the sources, then just right click on the folder you created and select "SVN Update". Using TortoiseSVN is really this easy!
+
+= Install MinGW =
+
+MinGW is a free C/C++ compiler suite for Windows. We only need the make utility from it but installing the whole MinGW package might be easier since it will set up the environment automatically (i.e. add the path to the make utility to the PATH environment variable).
+
+= Install NASM =
+
+NASM is the assembler that is used to compile the sources. Download the latest version and install. The installer will create shortcuts on the desktop and start menu that points to a batch file that sets up the environment for use with NASM. In other words, the path to NASM will be added to the PATH environment variable when using those shortcuts.
+
+= Install UPX (optional) =
+
+UPX is used to compress the XTIDE Universal BIOS configurator (XTIDECFG.COM) and the Serial Drive server software (SerDrive.exe). It is needed only for release builds to make these executable files smaller. Again, make sure that UPX.EXE can be found somewhere in the PATH.
+
+= Install Strawberry Perl (optional) =
+
+Strawberry Perl is required to execute optional scripts when building XTIDE Universal BIOS. Scripts include string compression (not needed unless you modify the sources) and checksum calculation. Just run the Strawberry Perl installer with default settings.
+
+----
+= Building XTIDE Universal BIOS =
+
+Open a command line window, using the shortcut created by the NASM installer, and go to the folder where you downloaded the sources with TortoiseSVN. Then go to the {{{XTIDE_Universal_BIOS}}} folder. Write {{{mingw32-make all}}} and all of the official BIOS binaries will be built.
+
+Continuing our example from above:[[BR]]
+{{{d:}}}[[BR]]
+{{{cd \Projects\XUB\XTIDE_Universal_BIOS}}}[[BR]]
+{{{mingw32-make all}}}
+
+You might want to write {{{mingw32-make checksum}}} instead if you installed Strawberry Perl as that will calculate and apply the checksums to the BIOS binaries during the build process. If you didn't install Strawberry Perl then you can use XTIDECFG.COM instead.
+
+You will find the binaries in the "Build" folder.
+
+== Including and excluding optional modules ==
+
+There are many optional modules (most of them are included in the official release builds). The reason for modules is simple: it is not possible to get all features to fit in an 8k ROM. Official builds are designed so that they include the features most users prefer.
+
+It is easy to include and exclude modules but it must be done by editing the makefile. The makefile specifies how the binaries are built when you execute "mingw32-make".
+
+Open the makefile with your favorite text editor (we highly recommend using [http://notepad-plus-plus.org/ Notepad++]). You will now see a list of all the modules and other build options and a short description for each. At the time of writing, this is what the list of options looks like:
+{{{
+####################################################################################################
+# Makefile to build XTIDE Universal BIOS.                                                          #
+#                                                                                                  #
+# Valid makefile targets are:                                                                      #
+# all       Removes existing files and builds binary files in \Build (without checksums)           #
+# small     Builds only binaries smaller than or equal to 8 kiB (without checksums)                #
+# large     Builds only binaries larger than 8 kiB (without checksums)                             #
+# custom    Builds custom binary without checksum (change DEFINES_CUSTOM / BIOS_SIZE_CUSTOM first) #
+# clean     Removes all files from \Build                                                          #
+# checksum* Same as 'all' but also applies checksums to the binaries                               #
+# strings*  Compress src\Strings.asm to src\StringsCompressed.asm                                  #
+# unused*   Checks if there are any unused functions that can be removed to save space             #
+#                                                                                                  #
+# * at the end of target name means that Perl is required for the job.                             #
+# Build directory must be created manually if it does not exist.                                   #
+#                                                                                                  #
+#                                                                                                  #
+# Following modules can be included or excluded:                                                   #
+# MODULE_8BIT_IDE             Support for 8-BIT IDE cards like XTIDE                               #
+# MODULE_8BIT_IDE_ADVANCED    Support for memory mapped and DMA based cards like JRIDE and XTCF    #
+# MODULE_ADVANCED_ATA         Native support for some VLB IDE controllers (requires USE_386)       #
+# MODULE_COMPATIBLE_TABLES    Support for ill behaving software that tries to access DPT directly  #
+# MODULE_BOOT_MENU            Boot Menu for selection of drive to boot from                        #
+# MODULE_EBIOS                Enhanced functions for accessing drives over 8.4 GB                  #
+# MODULE_HOTKEYS              Hotkey Bar to boot from any drive                                    #
+# MODULE_IRQ                  IDE IRQ support                                                      #
+# MODULE_SERIAL               Virtual hard disks using serial port                                 #
+# MODULE_SERIAL_FLOPPY        Virtual floppy drives using serial port (requires MODULE_SERIAL)     #
+# MODULE_STRINGS_COMPRESSED   Use compressed strings to save space                                 #
+# MODULE_VERY_LATE_INIT       Initialize on INT 13h if our INT 19h handler is not called           #
+# MODULE_POWER_MANAGEMENT     Power Management support                                             #
+# MODULE_WIN9X_CMOS_HACK      Hack for Windows 9x compatibility                                    #
+# MODULE_MFM_COMPATIBILITY    Restores BDA drive count for MFM controllers that expect to be the   #
+#                             only hard drive controller on the system                             #
+#                                                                                                  #
+# Not modules but these affect the assembly:                                                       #
+# ELIMINATE_CGA_SNOW          Prevents CGA snowing at the cost of a few bytes                      #
+# RELOCATE_INT13H_STACK **    Relocates INT 13h stack to beginning of stolen conventional memory   #
+# NO_ATAID_VALIDATION ***     Excludes code that tries to ensure proper communication with drives  #
+# NO_ATAID_CORRECTION         Excludes code that corrects illegal CHS values from some CF cards    #
+# USE_186                     Use instructions supported by 80188/80186 and V20/V30 and later      #
+# USE_286                     Use instructions supported by 286 and later (defines USE_UNDOC_INTEL)#
+# USE_386                     Use instructions supported by 386 and later (defines USE_286)        #
+# USE_AT                      Use features supported on AT and later systems (not available on XT) #
+# USE_UNDOC_INTEL             Optimizations for Intel CPU:s - do NOT use on NEC V20/V30/Sony CPU:s #
+# USE_NEC_V                   Optimizations for use with NEC V20/V30 processors only               #
+# CLD_NEEDED                  Only needed for compatibility with buggy software/BIOSes             #
+#                                                                                                  #
+# ** AT Builds only (when USE_AT is defined)                                                       #
+# *** Use this only when certain known good drives are not being detected (eg WD Caviars)          #
+####################################################################################################
+}}}
+
+There might be more modules and build options in the future so make sure to check the makefile after doing "SVN Update".
+
+Scroll down the makefile to find 'Assembler preprocessor defines' and 'Other variables':
+{{{
+##################################
+# Assembler preprocessor defines #
+##################################
+DEFINES_COMMON = MODULE_STRINGS_COMPRESSED MODULE_HOTKEYS MODULE_8BIT_IDE MODULE_EBIOS MODULE_SERIAL MODULE_SERIAL_FLOPPY MODULE_POWER_MANAGEMENT NO_ATAID_VALIDATION CLD_NEEDED
+DEFINES_COMMON_LARGE = MODULE_BOOT_MENU MODULE_8BIT_IDE_ADVANCED MODULE_COMPATIBLE_TABLES
+
+DEFINES_XT = $(DEFINES_COMMON) ELIMINATE_CGA_SNOW MODULE_8BIT_IDE_ADVANCED
+DEFINES_XTPLUS = $(DEFINES_XT) USE_186
+DEFINES_AT = $(DEFINES_COMMON) USE_AT USE_286 MODULE_IRQ MODULE_COMPATIBLE_TABLES
+DEFINES_386 = $(DEFINES_AT) USE_386 MODULE_ADVANCED_ATA MODULE_WIN9X_CMOS_HACK
+
+DEFINES_XT_LARGE = $(DEFINES_XT) $(DEFINES_COMMON_LARGE)
+DEFINES_XTPLUS_LARGE = $(DEFINES_XTPLUS) $(DEFINES_COMMON_LARGE)
+DEFINES_AT_LARGE = $(DEFINES_AT) $(DEFINES_COMMON_LARGE)
+DEFINES_386_LARGE = $(DEFINES_386) $(DEFINES_COMMON_LARGE)
+
+DEFINES_XT_TINY = MODULE_STRINGS_COMPRESSED MODULE_8BIT_IDE NO_ATAID_VALIDATION NO_ATAID_CORRECTION CLD_NEEDED
+
+DEFINES_CUSTOM = ?
+
+
+###################
+# Other variables #
+###################
+
+# Target size of the BIOS, used in Main.asm for number of 512B blocks (CNT_ROM_BLOCKS) and by checksum Perl script below ('make checksum').
+# Note! The size must be a multiple of 2 KB for compatibility reasons.
+BIOS_SIZE_TINY = 4096
+BIOS_SIZE_SMALL = 8192
+BIOS_SIZE_LARGE = 10240
+BIOS_SIZE_CUSTOM = ?
+}}}
+
+This is the only part of the makefile that you need to edit. The defines tell what modules and build options are included in what builds.
+
+DEFINES_COMMON define the modules that are included in almost all builds, with the Tiny build being the exception, and DEFINES_COMMON_LARGE define additional modules for all large builds.
+
+DEFINES_XT, DEFINES_XTPLUS and DEFINES_AT define what modules are included in the 8k XT, XT+ and AT builds in addition to the ones in DEFINES_COMMON.
+
+DEFINES_XT_LARGE, DEFINES_XTPLUS_LARGE and DEFINES_AT_LARGE are for large builds.
+
+Finally there are DEFINES_XT_TINY (XT build with minimal features) and DEFINES_386 as well as DEFINES_386_LARGE (AT builds for 386+).
+
+=== Creating a custom build ===
+
+So far we have only discussed the options used for the official builds. Since you are reading this there's a good chance that you want to create a custom build. For this reason the makefile target 'custom' was created. All you need to do is fill in the desired BIOS size (in bytes) after {{{BIOS_SIZE_CUSTOM = }}}, then fill in the modules and other build options you want after {{{DEFINES_CUSTOM = }}}. Since these lines will ''(should)'' never be changed on the server, conflicts, if any, will be easy to resolve whenever you do a "SVN Update" in the future. This minimizes the risk of losing the particular build options you use in your custom build.
+
+Anyway, for example, let's say that you want to create a custom XT-build for installation in an 8 KB ROM in the ROM socket on a Silicon Valley Computer ADP50L IDE controller.
+
+Since these controllers use memory mapped I/O and the I/O window is located at offset 1D00h (7424 in decimal) within the ROM segment, we obviously can't use all of the 8 KB ROM as our BIOS size. We also can't use the exact offset to the I/O window as PC option ROM BIOS sizes are always a multiple of 512 bytes. So, can we make it exactly 7 KB (7168 bytes)? No, because that will make it incompatible with some system BIOSes that require the size of option ROM BIOSes to be a multiple of 2 KB.
+
+So we make the BIOS size 6 KB.[[BR]]
+{{{BIOS_SIZE_CUSTOM = 6144}}}[[BR]]
+
+Since we now know the size constraints we can start selecting modules and other build options. A good starting point is to use the same options and modules as the official small XT-build and then add or remove options as needed - some trial and error will be required to reach the desired size.
+
+Note that the size of each module depends on what ''other'' modules are included so it's not feasible to list exact module sizes as there are so many combinations possible. Besides, the module sizes can and likely will change with every revision of the BIOS. The numbers mentioned below are just examples that are valid at the time of writing this.
+
+When running {{{mingw32-make custom}}} it's clear that the build is too large to fit in 6 KB so we have to decide what to remove.
+
+The module required for supporting the ADP50L controller, {{{MODULE_8BIT_IDE_ADVANCED}}}, is already included, and since that automatically includes {{{MODULE_8BIT_IDE}}} we can remove the latter to shorten the string of options. By the way, the same applies to {{{MODULE_SERIAL_FLOPPY}}} and {{{MODULE_SERIAL}}} respectively.
+
+To reduce the BIOS size we decide to remove {{{MODULE_EBIOS}}} since we won't need support for drives larger than 8 GB. This in turn means we can add {{{NO_ATAID_CORRECTION}}} since drives smaller than 8GB won't report more cylinders than allowed by the ATA specification. This is enough as we are down to 6133 bytes.
+
+So the build options should look something like this (all on one line):[[BR]]
+{{{DEFINES_CUSTOM = MODULE_8BIT_IDE_ADVANCED MODULE_STRINGS_COMPRESSED MODULE_HOTKEYS MODULE_SERIAL_FLOPPY MODULE_POWER_MANAGEMENT NO_ATAID_CORRECTION NO_ATAID_VALIDATION CLD_NEEDED ELIMINATE_CGA_SNOW}}}
+
+Alternatively, we could decide to remove just the serial drive stuff ({{{MODULE_SERIAL}}} and {{{MODULE_SERIAL_FLOPPY}}}) and that frees up so much space that we are down to 5785 bytes, well within the target size.
+
+So the build options then becomes (again, all on one line):[[BR]]
+{{{DEFINES_CUSTOM = MODULE_8BIT_IDE_ADVANCED MODULE_STRINGS_COMPRESSED MODULE_HOTKEYS MODULE_EBIOS MODULE_POWER_MANAGEMENT NO_ATAID_VALIDATION CLD_NEEDED ELIMINATE_CGA_SNOW}}}
+
+Many combinations are possible and it all depends on your needs and your specific hardware. Which brings us to...
+
+=== Module information ===
+
+Note! Without any of the controller related modules below you will only have support for standard 16-bit IDE controllers in 16-bit mode.
+
+==== {{{MODULE_8BIT_IDE}}} ====
+This module contains support for XTIDE rev 1 and XTIDE rev 2 (both the regular transfer mode as well as the one created specifically for use with Olivetti M24 and friends). This module is also needed for using 16-bit IDE controllers in 8-bit mode.
+
+==== {{{MODULE_8BIT_IDE_ADVANCED}}} ====
+This module contains support for JR-IDE/ISA, Silicon Valley Computer ADP50L and all variants of the Lo-Tech XT-CF boards.
+
+This module requires and automatically includes {{{MODULE_8BIT_IDE}}}.
+
+==== {{{MODULE_ADVANCED_ATA}}} ====
+Adds native support for VLB (and hopefully in the future also PCI) IDE controllers. There is currently support for QDI Vision QD6500 and QD6580 VLB IDE controllers. There is also experimental support for Promise PDC 20230-C and 20630 VLB IDE controllers but this needs more testing.
+
+This module requires {{{USE_386}}}.
+
+==== {{{MODULE_EBIOS}}} ====
+Support for Phoenix Enhanced Disk Drive Specification. Allows to access more than 8 GB but requires support from operating system (Windows 9x and later).
+
+==== {{{MODULE_COMPATIBLE_TABLES}}} ====
+TBD
+
+==== {{{MODULE_BOOT_MENU}}} ====
+The boot menu displays drive details and allows selecting boot drives more easily but it has essentially all the same features as {{{MODULE_HOTKEYS}}}. It can also be included without {{{MODULE_HOTKEYS}}}, in which case the menu is always entered during the boot process.
+
+==== {{{MODULE_HOTKEYS}}} ====
+Displays hotkeys during drive detection. Hotkeys allows boot drive selection, ROM Boot, Serial Drive Scanning and Boot Menu.
+
+==== {{{MODULE_IRQ}}} ====
+Adds IRQ support (you also need to enable IRQ with XTIDECFG.COM). IRQs have no real benefit in DOS and can actually slow transfer rates a bit. You might want to use IRQs with more capable operating systems.
+
+==== {{{MODULE_SERIAL}}} ====
+Adds support for virtual hard disks using serial port. [SerialDrives Instructions for emulating Serial Drives with the XTIDE Universal BIOS]
+
+==== {{{MODULE_SERIAL_FLOPPY}}} ====
+Adds support for virtual floppy drives using serial port.
+
+This module requires and automatically includes {{{MODULE_SERIAL}}}.
+
+==== {{{MODULE_STRINGS_COMPRESSED}}} ====
+Use compressed strings to save ROM space. This module should always be included as there is no downside to using it.
+
+==== {{{MODULE_VERY_LATE_INIT}}} ====
+TBD
+
+==== {{{MODULE_POWER_MANAGEMENT}}} ====
+Power Management support (you also need to enable it with XTIDECFG.COM). If you know that the BIOS will only handle drives with flash based storage (i.e. no drives of the spinning rust variety) then you can save a little bit of ROM space by not including this module.
+
+==== {{{MODULE_WIN9X_CMOS_HACK}}} ====
+This module tries to ensure that a dummy drive is installed in the system BIOS harddrive configuration in CMOS. It won't work, and won't attempt to do anything, if the system BIOS is using a non-standard method of checksumming the CMOS. In such cases you must add the dummy drive manually by using the computers system BIOS Setup program. Note that you might want to do that anyway if you need to omit this module to save ROM space.
+
+This module requires {{{USE_386}}}.
+
+==== {{{MODULE_MFM_COMPATIBILITY}}} ====
+This module is made to improve compatibility, and to allow XTIDE Universal BIOS to coexist, with other harddrive controller BIOSes.
+
+Quite a few harddrive controller BIOSes are made with the assumption that a maximum of two harddrives can be installed in a system. They will refuse to install their own drive(s) if they detect that doing so will exceed that count. They check that by reading the count of installed harddrives in the BIOS Data Area (BDA) during initialization. For various reasons, XTIDE Universal BIOS must be the last harddrive BIOS to be initialized at boot, so this in itself is not a problem as XUB will add its drive count to the BDA last. However, when chaining interrupt 13h calls to the previous handler (the other BIOS), the count will reflect the true number of harddrives installed and that might possibly confuse the other BIOS. This is why this module was created. It will restore the drive count to what the other BIOS expects, before chaining to it.
+
+The downside of using this module is that it will make the build larger and add processing overhead. Basically, you should only use this if you know you need it. Note that despite the name, this module applies to other controller types as well, such as SCSI. Generally speaking, you only need this if you want XUB to coexist with very old harddrive controllers that have their own BIOS.
+
+''Also note that the code in this module has not been tested yet so we don't even know if it works. If you do try it and it works, please let us know!
+
+=== Other features that affect assembly ===
+
+==== {{{ELIMINATE_CGA_SNOW}}} ====
+Prevents CGA "snowing" when rendering the boot menu at the cost of a slightly bigger BIOS. If you're not including {{{MODULE_BOOT_MENU}}} then you can probably omit this as well.
+
+==== {{{RELOCATE_INT13H_STACK}}} ====
+Can only be used in AT-builds. When using this, the BIOS will switch to its own stack located at the top of "stolen" conventional memory on every interrupt 13h call. This is useful for debugging purposes but is not recommended for regular use since it adds overhead that reduces performance slightly.
+
+==== {{{NO_ATAID_VALIDATION}}} ====
+TBD
+
+==== {{{NO_ATAID_CORRECTION}}} ====
+Some Compact Flash cards (Sandisk Ultra 16 GB and 32 GB cards, for example) violates the ATA specification by having a cylinder count higher than the maximum allowed by the standard (16383 cylinders). To avoid problems from this, the BIOS includes code that will limit the cylinder count to this maximum. If you know that the drive(s) you will use all conform to the specification then you can use this build option to save some ROM space.
+
+Note that you can use BIOSDRVS.COM to check the cylinder count.
+
+==== {{{USE_186}}}, {{{USE_286}}} and {{{USE_386}}} ====
+Determines what CPU instructions are allowed. {{{USE_186}}} allows use of instructions supported by processors up to and including 80188/80186 and NEC V20/V30. The same applies to {{{USE_286}}} and {{{USE_386}}} respectively. XTIDE Universal BIOS uses macros that, when necessary, emulates instructions not available on older processor generations. Do not use any of these if you want to generate 8088/8086 compatible code.
+
+==== {{{USE_UNDOC_INTEL}}} ====
+Allows use of undocumented Intel opcodes that are not supported by NEC V20/V30. This is defined automatically when {{{USE_286}}} or {{{USE_386}}} is defined. Note that you can still use this with an 8088/8086 compatible BIOS build if you know that it will never run on a NEC V20/V30 processor.
+
+==== {{{USE_NEC_V}}} ====
+Allows use of instructions available only on NEC V20/V30 processors.
+
+==== {{{USE_AT}}} ====
+Assembles code targeted for AT systems. For example, AT-builds always operate in Full Operating Mode. Another difference is that AT-builds use some BIOS functions that are not available on XT systems.
+
+==== {{{CLD_NEEDED}}} ====
+This puts CLD instructions in strategic places in the code to safeguard against buggy software that leaves the Direction Flag set. This is ''extremely'' rare so this define should not be needed but on the other hand there's very little overhead from using this. If in doubt, use it.
+
+----
+= Building the Configurator (XTIDECFG.COM) =
+
+Go to "XTIDE_Universal_BIOS_Configurator_v2" folder and write {{{mingw32-make all}}} to build the XTIDECFG.COM. You should write {{{mingw32-make release}}} if you installed UPX.
+
+Again, you will find the binary in the "Build" folder.
+
+----
+= Building the Serial Drive server software (SerDrive.exe) =
+TBD