TSUNAMI software y Eduardo A. Robsy Petrus se complacen en presentarles:



                      
                               
                                             
                                  
                                  
                                       
                                          
                               

          v.0.01a - Ensamblador de Z80/MSX para ordenadores IBM/PC








  HISTORIAL
-----------------------------------------------------------------------------
  v.0.01a - [06/07/2000] - Versin preliminar, primera publica.


  MIS EXCUSAS
-----------------------------------------------------------------------------
  Creo que es prudente empezar excusndome. A muchos les parecer una auntn-
    tica blasfemia un ensamblador cruzado MSX/PC. A m tambin. Lo que sucede
    es que no tengo ningn MSX lo suficientemente potente como para trabajar
    con l cmodamente: me faltan dispositivos de almacenamiento, memoria RAM
    y editores adecuados. Por eso me he decidido a escribir un ensamblador
    especfico para MSX en otra plataforma: el IBM/PC. Es triste, pero me
    resulta mucho ms cmodo programar para MSX desde el PC, porque puedo
    manejar un cdigo fuente mucho mayor con mayor facilidad, y el ensamblado
    es casi automtico.
  No pretendo que todo el mundo use el asMSX, pero creo que podr serles de
    utilidad a los pobres desheredados que, como yo, no tienen un ordenador
    MSX lo suficientemente preparado. Si tuviera un Turbo-R no empleara este
    ensamblador, palabra.


  INTRODUCCION
-----------------------------------------------------------------------------
  El propsito principal de asMSX es conseguir un ensamblador potente y versa-
    til, a la vez que fiable y rpido. Con estas premisas como punto de par-
    tida, ha sido escrito en C y compilado para MS-DOS con el DJGPP v.2.
  El resultado es una aplicacin de algo menos de 60 KBs y con una velocidad
    de ensamblado muy elevada, del orden de 25.000 lineas por segundo en un
    ordenador Pentium MMX a 233 MHz. La velocidad final depende del ordenador
    empleado y de la complejidad del cdigo a ensamblar, pero aun as debera
    ser posible ensamblar 64 KB en no ms de unos segundos.
  Adems de esto, incorpora soporte para multiples sintaxis, como son la
    oficial de Zylog y la estandarizada, as como soporte para todos los mne-
    mnicos, tanto los oficiales como los indocumentados del Z80.
  Completan el ensamblador una serie de directivas de compilacin y pseudo
    instrucciones especficas para facilitar la labor del programador a la
    hora de organizar el programa o acceder a la BIOS del MSX.


  REQUISITOS DEL SISTEMA
-----------------------------------------------------------------------------
  Para poder utilizar este programa necesitaris bien poquitas cosas: bastar
    con un ordenador con procesador 80386 o superior, 1 MB de memoria mnima
    y sistema operativo MS-DOS o compatible (DR-DOS, IBM-DOS, Windows'9x).
  Aparte de eso, para editar el cdigo fuente os valdr cualquier editor de
    textos en formato ASCII. A mi me va perfecto el Edit del DOS, pero habr
    quien prefiera el VI, o el ED, o el XED o cualquier otro. Tanto da: basta
    con que a vosotros os sea cmodo.
  Para ejecutar los binarios producidos por el ensamblador en sus diversos
    formatos hay varias opciones. La ms cmoda es copiar el binario obtenido
    a un disquette y cargarlo directamente en un MSX real. La otra opcin es
    menos cmoda: recurrir a los emuladores de MSX para PC, muy abundantes y
    ms o menos fiables. Ningn emulador es perfecto, pero el que ms se
    acerca es el BrMSX, aunque su debugger no es gran cosa. Para depurar los
    programas recomiendo el NO$MSX, que tiene un debugger fantstico, si bien
    la emulacin dista mucho de ser perfecta (el sonido suena a lata).


  FUNCIONAMIENTO DEL ENSAMBLADOR
-----------------------------------------------------------------------------
  El funcionamiento de asMSX es sencillo: simplemente hay que ejecutarlo
    pasndole el nombre del archivo a ensamblar en la lnea de comandos. Es
    decir, si queremos ensamblar PRUEBA.ASM, simplemente habr que escribir
    desde el prompt: asMSX PRUEBA.ASM (o como la extensin ASM est predefi-
    nida, bastar con indicar asMSX PRUEBA).
  En cuanto al formato de los ficheros ASM, es bien sencillo: son archivos de
    texto plano (ASCII). A mi me va muy bien el EDIT para MS-DOS que viene
    con Windows'9x, porque soporta varios ficheros abiertos a la vez y porque
    aguanta ficheros bastante grandecitos...


  PSEUDO-INSTRUCCIONES Y COMANDOS
-----------------------------------------------------------------------------
  En el cdigo fuente, el programa en ensamblador, el programador dispone de
    una serie de pseudo-instrucciones especficas para ayudarle en su tarea.
  A continuacin haremos un listado rpido y un breve comentario:

  ORG Direccin

    Muy tpica de casi todos los ensambladores. Indica a partir de que di-
      reccin se va a realizar el ensamblado de las instrucciones sucesivas.
      No puede quebrarse as la longitud mxima de cada bloque.

  DB valor[,valores]
  DEFB valor[,valores]

    Sirve para definir una secuencia de valores almacenados como bytes, es
      decir, ocupando slo una posicin de memoria. Si se tratan de almacenar
      valores que no caben, sern recortados, almacenndose slo el byte bajo
      o menos significativo de la expresin. Puede darse un slo valor o una
      sucesin de los mismos, separados por comas. Tambin se puede incluir
      texto entrecomillado, que se almacenar en ASCII, un byte por carcter.
      Por ejemplo: DB "Bonito da",13,10,"Qu tal ests?"

  DT valor[,valores]
  DEFT valor[,valores]

    Es sinnimo del anterior, se ha incluido por compatibilidad con otros en-
      sambladores ms antiguos, que obligaban a que los textos fueran inclui-
      dos de esta forma.

  DW valor[,valores]
  DEFW valor[,valores]

    Realiza funcin idntica a DB, pero almacena los valores como words, es
      decir, palabras de 16 bits en lugar de 8 bits (bytes).

  DS valor
  DEFS valor

    Al contrario que las anteriores, no almacena ningn valor en memoria,
      pero s que ocupa un espacio equivalente de bytes. Sirve para reservar
      espacio para variables o menesteres semejantes.

  INCBIN "fichero.ext"

    Con esta instruccin se incluye un fichero binario, que simplemente ser
      posicionado en el banco actual, ocupando tantos bytes como tenga. La
      funcin principal es incluir grficos en formato de GameBoy de una
      forma elegante.

  Identificador EQU Valor
  Identificador=Valor

    Esta instruccin asigna al identificador dado un valor numrico, que
      puede referenciarse como otro identificador ya definido, o por un nume-
      ro o por el resultado de una operacin ms compleja. Es til para defi-
      nir direcciones o valores que se emplearn mucho.

  DEBUG "texto"

    Esta funcin es muy especfica. Guarda efectivamente el mensaje entreco-
      millado en el binario de salida, pero su ejecucin es trasparente, es
      saltado al ejecutar el programa. Eso s, algunos emuladores como el
      NO$MSX pueden leerlo e indicarlo. Podr verse tambin con cualquier
      debugger. Se trata de una herramienta para la depuracin.

  PRINTTEXT "texto"
  PRINTSTRING "texto"

    Esto imprimir el mensaje indicado en el fichero de texto de salida.
      Sirve para ver hasta donde se ha ensamblado, y en qu orden se ha
      hecho, o para simplemente hacer alguna indicacin.

  PRINT [nmero|identificador]
  PRINTDEC [nmero|identificador]

    Al igual que la directiva anterior, imprimir un mensaje, pero esta vez
      ser un valor numrico, o el valor de un identicador o etiqueta, y
      expresado en decimal.

  PRINTHEX [nmero|identificador]

    Al igual que la directiva anterior, imprimir un mensaje, pero esta vez
      ser un valor numrico, o el valor de un identicador o etiqueta, y
      expresado en hexadecimal.

  Estas son las directivas generales para ensamblado del Z80. Pero asMSX no
    se llama as por casualidad: tiene una serie de instrucciones especiales
    para facilitar la labor del programador de MSX:

  MSX

    Esta pseudoinstruccin define como constantes numricas todos las sub-
      rutinas de la BIOS de los MSX de la primera generacin. Por tanto,
      en lugar de emplear la instruccin CALL $006c puede emplearse el nombre
      de la entrada de la BIOS correspondiente, CALL INITXT. No se aade nin-
      guna funcionalidad adicional, pero facilita mucho la tarea.

  MSX2

    Esta pseudoinstruccin, al igual que la anterior, define como constantes
      numricas las rutinas de la BIOS de los MSX2, esto es, de los MSX de la
      segunda generacin. Al emplear la directiva MSX2 quedan automticamente
      definidas las entradas de la BIOS de los MSX de primera generacin. La
      nica peculiaridad es que las rutinas de la SUB-ROM quedan definidas
      con el prefijo SUB_. De este modo, la rutina REDCLK de la SUB-ROM de
      los MSX2 queda definida como SUB_REDCLK. Adems se habilita la pseudo-
      instruccin CALL_SUB, que se ver ms adelante.

  BASIC
  MSXBASIC

    Con este comando se establece el formato de salida del ensamblador como
      binario de MSX-BASIC, esto es, con la cabecera que permite cargar el
      archivo desde BASIC con la instruccin BLOAD. La cabecera generada es
      la siguiente:

        Identificador       BYTE $FE
        Direccin inicial   WORD $XXXX
        Direccin final     WORD $XXXX
        Direccin ejecucin WORD $XXXX

    Las direcciones inicial y final las fija automticamente el ensamblador
      en funcin del programa ensamblado. La direccin de ejecucin ser
      igual a la direccin inicial siempre que no se emplee el comando START.
    ATENCION: Para que el programa sea ejecutable desde BASIC deber situarse
      en una posicin vlida, esto es, para un MSX con 64 KB o ms, a partir
      de la posicin $8000. Cuidado tambin con situarlo en la zona de las
      variables del sistema: los resultados pueden ser desastrosos.

  START Direccion
  EXEC Direccion
  EXECUTION Direccion

    Este comando slo tiene sentido cuando se ha empleado el anterior, es
      decir, cuando se va a producir un archivo binario para BASIC. Se esta-
      blece la direccin de ejecucin del programa, esto es, cual es la
      direccin de la primera instruccin a ejecutar.

  DOS
  MSXDOS

    Con esta pseudoinstruccin se establece el formato de salida como un
      archivo directamente ejecutable desde el MSX-DOS (es decir, un programa
      con la extensin .COM). Con esta instruccin se fija automticamente la
      direccin de inicio del programa, que debe ser $0100, porque ser la
      direccin en la que el sistema operativo cargue el archivo. Adems, se
      habilita la pseudoinstruccin CALL_DOS.

  CALL_SUB Direccion
  CALLSUB Direccion
  CALL_SUBROM Direccion
  CALLSUBROM Direccion

    Esta macroinstruccin realiza directamente una llamada a una subrutina de
      la BIOS situada en la SUB-ROM o EXT-ROM del MSX2. Por ejemplo, para
      acceder a la funcin REDCLK emplearamos CALL_SUB $01f5 en lugar de
      desarrollarlo paso por paso:

                 LD IX,$01f5 ; Cargar en IX la direccin de la subrutina
                 CALL $015c  ; Llamar a la subrutina EXTROM

    El ensamblador abrevia esto y guarda directamente el desarrollo.

  CALL_DOS Direccion
  CALLDOS Direccion

    Este comando sirve para realizar una llamada a una funcin del MSX-DOS
      de forma automtica. Slo ser posible emplearlo cuando se haya selec-
      cionado el formato de salida de MSX-DOS. As, CALL_DOS $02 equivale a:

                LD C,$02
                CALL $0005

    Una vez ms, el ensamblador acorta el trabajo.


  Y esas son todas las pseudoinstrucciones o macros que soporta esta versin
    del asMSX. Eso s, si no se elige un formato en concreto de salida, ya
    sea MSX-BASIC o MSX-DOS, el ensamblador crear por defecto ficheros
    binarios puros para Z80, sin ningn tipo de cabecera o correccin.
  Un detalle final es que tanto da que las directivas o pseudo-instrucciones
    estn en maysculas o minsculas, y que, opcionalmente, puede indicarse
    un punto delante de ellos, por compatibilidad con otros ensambladores.
    En cualquier caso ser opcional. Por tanto, sern equivales, por ejemplo
    PRINT print Print o pRiNt.


  CONSTANTES NUMRICAS
-----------------------------------------------------------------------------
  asMSX permite emplear diversos sistemas de numeracin y diferentes sintaxis
    para indicarlos. Son todas equivalentes. Adems, admite las operaciones
    bsicas entre dichos valores, que sern calculadas al ensamblar, no en
    tiempo de ejecucin.

  Hexadecimal [Base 16]: Se indican empezando por 0x o por $, o bien termi-
    nando con una h o H. Por tanto, seran equivalentes 0xaaaa, $aaaa o bien
    aaaaH. Tanto da que los caracteres estn en maysculas o en minsculas.

  Octal [Base 8]: Se indican empezando por 0 o terminando por o  O. As, el
    nmero 020 sera igual a 20o.

  Binario [Base 2]: Se indican exclusivamente terminando con un b o B. Por
    ejemplo, el nmero 11001010b.

  Decimal [Base 10]: Se indican directamente, o bien acabando con una d o D.

  Los identificadores, ya sean etiquetas o no, tambin tendrn un valor nu-
    mrico. El valor de las etiquetas ser igual al lugar donde apuntan. Por
    ejemplo despus de ejecutar:

               org $8000
               inicio:

    La etiqueta inicio valdr $8000.

  Con todos estos valores vistos se pueden realizar operaciones aritmticas
    bsicas, indicandolo con los siguientes operadores:

      Suma :          +
      Resta:          -
      Multiplicacin: *
      Divisin:       /
      Mdulo (resto): %

  Adems, podrn emplearse los parntesis para delimitar el orden.
    Por ejemplo, sera vlido como nmero $50*16+40-2/3*(40+9)/020+inicio
    Eso s, debe tenerse en cuenta que los clculos se realizan en aritme-
    tica de enteros. Por tanto, 6/4=1 y 6%4=2.

  Se han incorporado tambin operaciones de desplazamiento.

      Desplazamiento a la izquierda (shift):  <<
       Ejemplo: $01<<2 desplazara a la izquierda $01 dos bits, es decir $04.

      Desplazamiento a la derecha (shift):    >>
       Ejemplo: $08>>1 desplazara a la derecha $01 un bit, es decir $04.

  Finalmente, se han implementado tambin operaciones lgicas a nivel de bit:

      Negacin (complemento a 1): ~   (es un operador unario)
       Ejemplo: ~$01 sera igual a $FE.

      AND binario: &
      OR binario:  |
      XOR binario: ^

  Para la gente que est acostumbrada a programar en C ser fcil adaptarse,
    porque son los mismos operadores que emplea este lenguaje.


  IDENTIFICADORES
-----------------------------------------------------------------------------
  Los identificadores y etiquetas son texto sin entrecomillar. La longitud,
    en principio, es ilimitada, pero tampoco conviene abusar, para no sobre-
    cargar la memoria y ralentizar el ensamblado. Todos los identificadores
    deben empezar por una letra (mayscula o minscula) o bien por la barra
    baja (_). El resto de caracteres podrn ser alfanumricos o barra baja.
  Como ejemplos de identificadores, tenemos _hola, mierda, r2D2, o_sea_Borja
    y cualquiera otro imaginable.
  Es muy importante decir que los identificadores s que distinguen entre
    las maysculas y las minsculas, es decir, hola ser distinto de HOLA.
    El resto de instrucciones, registros y directivas no sufren esta res-
    triccin, por lo que PRINT podr indicarse como pRiNT.


  ETIQUETAS
-----------------------------------------------------------------------------
  Hay dos tipos de etiquetas: las globales y las locales, dependiendo de su
    mbito. Las etiquetas globales podrn ser accedidas desde cualquier pun-
    to del programa. Para definir una etiqueta global basta con darle un
    identificador y poner dos puntos a continuacin. Por ejemplo

      etiqueta_global:

    As quedara definida. Sin embargo, para acceder a ella no hace falta
    poner los dos puntos, por ejemplo:

      jp etiqueta_global

    En cambio, las etiquetas locales siempre empiezan por @@. Por tanto, para
    definir una etiqueta local deberemos indicar @@ identificador :. Por
    ejemplo:

      @@soy_local:

    Y para llamarla, por supuesto, quitaremos los dos puntos, pero no los
    smbolos de arroba:

      jp @@soy_local

    La peculiaridad de las etiquetas locales es que slo existen en el cdigo
    indicado entre una etiqueta global y otra. Por tanto, pueden definirse
    varias con el mismo identificador siempre que haya alguna etiqueta local
    definida entre ellas.
    El siguiente cdigo sera perfectamente vlido

     ld a,0
     @@bucle:
      inc a
      cp $ff
      jr nz,@@bucle

     subrutina:

     ld a,$ff
     @@bucle
      dec a
      cp $20
      jr nz,@@bucle

    Con las etiquetas globales, sin embargo, no podr haber duplicidades,
    tomndose la primera definicin como la correcta.


  APRENDER A PROGRAMAR EL MICROPROCESADOR Z80 Y EL MSX
-----------------------------------------------------------------------------
  Eso ya es harina de otro costal. Hay sitios muy buenos en internet para
    encontrar documentos y ejemplos. Por ejemplo, si os apetece, pasad por la
    pgina http://www.msx.org . Desde all podris encontrar todo tipo de
    informacin sobre el MSX.
  Tambin me gusta mucho FUNET por la cantidad de material que tiene, echadle
    un vistazo en ftp://nic.funet.fi , empleando login anonymous.
  Y en espaol tambin hay muchas pginas, que podris alcanzar desde los
    muchos links de http://www.aamsx.org
  Otros que tienen toneladas de links son los de http://www.file-hunter.com
  Pasead un poco y algo encontraris, seguro.
  Las documentaciones imprescindibles en cualquier caso son:

    Z80OPCOD.DOC : El documento ms completo sobre mnemnicos del Z80, tanto
    oficiales como no oficiales. Gracias a Sean Young (programador de vMSX).

    TREDBOOK.TXT : Versin digital de "The Red Book of MSX". Imprescindible
    para tener un conocimiento profundo sobre el MSX.

    MSX2 Technical Handbook : La documentacin definitiva sobre el MSX2.
    Es un compendio gigantesco de documentacin sobre hardware y programacin
    de los ordenadores de segunda generacin. La versin digital se la debe-
    mos a Nestor Soriano.

  Slo con esto ya podis empezar. En dos semanas tenis un Nemesis (o casi).


  SALIDA DEL asMSX
-----------------------------------------------------------------------------
  En el caso de que no haya errores, asMSX generar los siguientes ficheros,
    suponiendo que hayamos ensamblado, por ejemplo, PRUEBA.ASM:

   PRUEBA.SYM : Una indicacin de los identificadores. Compatible con NO$MSX.
   PRUEBA.TXT : Si se us alguna directiva de tipo PRINT.

  Dependiendo de la opcin de formato, tambin se generar:

   PRUEBA.Z80 : Opcin por defecto, cdigo mquina de Z80 sin ms.
   PRUEBA.BIN : Fichero binario cargable desde MSX-BASIC con BLOAD.
   PRUEBA.COM : Fichero directamente ejecutable desde MSX-DOS.


  NUEVAS VERSIONES Y ACTUALIZACIONES
-----------------------------------------------------------------------------
  Esta es una versin preliminar, de depuracin, para corregir y comprobar el
    funcionamiento del motor de ensamblador del asMSX. Una vez que se pruebe
    su correccin se programar una nueva versin, con un preprocesador del
    cdigo fuente, lo que posibilitar la inclusin de otros ficheros de c-
    digo, la utilizacin de macroinstrucciones o incluso el ensamblado con-
    dicional, entre otras ventajas.
  Tambin est planeado, pero ms a largo plazo, el desarrollo de un entorno
    de trabajo, ya sea para MS-DOS o para Windows, con funcionalidades espe-
    cficas para programacin.
  Otra cosa que debe cambiar es la documentacin: esto es impresentable. La
    futura documentacin del programa, as como su logo, sern HTML.


  ERRORES Y FALLOS DEL asMSX
-----------------------------------------------------------------------------
  Alguno tiene, por supuesto, y alguno que yo no me haya imaginado tambin
    saldr. Lo que no funciona, y os aviso de salida, es el recuento de l-
    neas, que puede equivocarse un peln para arriba o para abajo al indicar
    un error. A veces acertar y otras no, indicando la lnea siguiente como
    errnea, o la anterior. Se corregir en la prxima versin.
  Esta es una versin preliminar, y no ha sido completamente depurada. Es
    muy posible que encontris errores, fallos inexplicables o ilgicos, o
    cualquier otro tipo de fallos o cuelgues. En cualquier caso, remitidme
    el cdigo fuente o la parte del programa que os d fallos, as como una
    breve indicacin del problema, y tratar de corregirlo.
  Si tenis cualquier duda sobre el ensamblador o sobre la programacin del
    Z80, no dudis en contactar conmigo por e-mail. Os responder lo antes
    posible.


  AGRADECIMIENTOS
-----------------------------------------------------------------------------
   Konami, porque NADIE ha programado jams tan bien un MSX.
   Marat Fayzullin, por ser pionero en la emulacin, gur de los micros.
   Sean Young, por su documentacin completsima sobre el Z80.
   Martin Korth (NO$CASH), por sus documentaciones, apoyo y por el NO$MSX.
   Ricardo Bittencourt, por el mejor emulador de MSX, el BrMSX.
   Nestor Soriano, por currrselo y pasar a TXT el MSX2 Tech. Handbook.
   Y a toda la pea de HispaMSX: algo se mueve, y somos nosotros.

-----------------------------------------------------------------------------
  TSUNAMI software 
-----------------------------------------------------------------------------
  Eduardo A. Robsy Petrus, 2.000
  e-mail: robsypetrus@teleline.es
-----------------------------------------------------------------------------
