Traducido a partir del documento MAKEROM.DOC original en Ingls.
N.T.> significa Nota del Traductor






               Instrucciones para el programa MS-DOS "MAKEROM"

       *****************************************************************

                                     AVISO

      Hewlett-Packard pone a disposicin de los clientes MAKEROM.EXE sin
      coste alguno para ayudarles en el desarrollo de aplicaciones para la
      HP 48SX, con las siguientes condiciones:

      N.T.> Se deja el texto legal en su versin original en Ingls.

       *  The program MAKEROM.EXE and the documentation file MAKEROM.DOC
          are provided "as is," and are subject to change without notice.
          Hewlett-Packard Company make no warranty of any kind with
          regard to the software or documentation, including, but not
          limited to, the implied warranties of merchantability and
          fitness for a particular purpose.  Hewlett-Packard Company
          shall not be liable for any error or for incidental or
          consequential damages in connection with the furnishing,
          performance, or use of this software and documentation.


       *  The program and documentation are copyrighted by Hewlett-
          Packard.  Sale of this material is prohibited without prior
          written permission of Hewlett-Packard Company.


       *  The HP Customer Support department does not support MAKEROM.
          Questions, comments, defect reports, etc. should be directed to
          the Library Development conference on the HP Calculator
          Bulletin Board System.  All responses from Hewlett-Packard will
          normally be provided through that conference.


       *  Software generated by MAKEROM.EXE should be tested and
          qualified in its final form.

      Las versiones revisadas del software y la documentacin se pondrn en
      la BBS tan pronto como estn disponibles.





















                                   -1-











      1. MAKEROM - Generador de Bibliotecas

      Las herramientas de desarrollo RPL (RPL Tools) RPLCOMP, SASM y SLOAD se
      pueden usar para crear objetos de cdigo individuales, pero no soportan
      fcilmente la creacin de un objeto biblioteca. MAKEROM es un
      preprocesador que lee un fichero de control y ficheros externos (con la
      extensin .ext) generados por el compilador RPL generando entonces la
      cabecera, hash y ficheros finales apropiados para la generacin de
      bibliotecas con el ensamblador Saturno y el Cargador.

      Las bibliotecas son una coleccin de objetos en forma precompilada que
      permiten un acceso rpido. La forma precompilada de una biblioteca
      incluye un nombre de biblioteca, una tabla "hash" que contiene todos
      los nombres de las palabras de usuario, una tabla "link", ordenada
      segn el nmero de las rutinas, con las direcciones de ejecucin de
      todas las rutinas, una tabla de mensajes opcional que contiene todos
      los mensajes para el controlador de errores y una rutina de
      configuracin que permite a la biblioteca hacer algo durante la
      configuracin (cuando se produce una Parada del Sistema). Tambin
      contiene un "checksum" (suma de comprobacin) que lo usa la HP 48 para
      verificar si la biblioteca es o no vlida ("Warning: Invalid Card Data"
      Advertencia: Datos de la Tarjeta Invlidos). La herramienta MAKEROM se
      usa para construir las diversas tablas. Un comando SLOAD crea el
      checksum.

      Las bibliotecas deben ser independientes de la direccin, porque pueden
      residir en cualquier sitio en los puertos 0, 1 o 2. Para ser
      independientes de la direccin, todas las referencias a las rutinas de
      la biblioteca se hacen mediante punteros rom. Un puntero rom es un
      objeto RPL con un prlogo de 5 nibbles (DOROMP) y un cuerpo de 6
      nibbles que contiene el identificador rom (llamado ID de Biblioteca
      para los usuarios) y el nmero de la rutina dentro de la biblioteca.
      Cuando se llama a una rutina de la biblioteca, el procesador determina
      si el rom est presente en el sistema, y si es as, determina la
      direccin de esa rutina y le transfiere el control, reconociendo as el
      hecho que se desconoce la direccin real de la rutina hasta el momento
      en que se llama a la rutina.

      Tres cosas le dicen al compilador RPL que convierta las referencias a
      las rutinas de la biblioteca en punteros rom. Primero, la directiva del
      compilador xROMID dice que se compilen ciertas rutinas como ROMs
      externas (bibliotecas) en lugar de hacerlo como una ROM incorporada en
      la HP-48. Segundo, todas las rutinas de bibliotecas se deben declarar
      con xNAME (o sNAME) en las palabras de usuario con nombre o NULLNAME en
      las palabras sin nombre -- NAMELESS no est permitido. Tercero, la
      directiva del compilador EXTERNAL identifica cuales de las rutinas
      NULLNAMEd (con nombres nulos) se compilarn como punteros rom.

      Las rutinas que no se declaran EXTERNAL se compilarn como punteros de
      objeto.









                                   -2-











      El lenguaje ensamblador se debe incluir entre las directivas
      CODE...ENDCODE a fin de ser independiente de la direccin. No se
      permite ninguna declaracin como CON(5) (*)+5, porque se cargan en
      direcciones especficas. Si se mueve ese cdigo a una direccin
      diferente, entonces fallar. Las declaraciones CON solo se pueden usar
      con valores, no con direcciones. Las direcciones se pueden referenciar
      con declaraciones REL.

      El proceso de generar un objeto biblioteca con MAKEROM no es trivial,
      as que se ilustrar aqu la estructura de los ficheros y los
      procedimientos que han sido usados por HP y otros desarrolladores para
      proyectos tales como La Tarjeta de la Biblioteca de Ecuaciones HP
      82211A o el Kit de Herramientas del Programador de la HP 48.

      El orden de los acontecimientos es:


         +  Compilar y ensamblar el fuente

         +  Usar MAKEROM para crear los ficheros cabecera, hash, fin y
            control de la carga.

         +  Usar el cargador (SLOAD) para construir la biblioteca a partir de
            los ficheros de salida generados por MAKEROM en combinacin con
            tu cdigo.

         +  Usar el cargador (SLOAD) para aadir una cabecera binaria para la
            transferencia del fichero al principio de la biblioteca y
            rellenar las referencias del sistema.

      Se usa una convencin en los nombres para dotar de cierta organizacin
      a todos los ficheros que comprenden una biblioteca completa. Se usa un
      prefijo de dos letras nico para distinguir una biblioteca de otras y
      se usa la extensin del fichero para indicar el tipo de un fichero. Por
      ejemplo, en el proyecto de la tarjeta de la Biblioteca de Ecuaciones,
      se us el prefijo PT para la biblioteca de la Tabla Peridica, CO se
      us para la biblioteca de Constantes, BR se us para el "browser"
      (examinador), etc. Tambin se usa el prefijo de dos letras para nombrar
      las rutinas internas dentro de la biblioteca. Esto se hace para ayudar
      a distinguir las rutinas de una biblioteca de las de otra.



















                                   -3-










      Las extensiones de los ficheros se definen como sigue:

         EXTENSION   SIGNIFICADO
         ---------   --------------------------------------------
            .A       Fichero fuente en ensamblador del Saturno
            .EXT     Listado externo generado por RPLCOMP
            .H       Fichero "include" (para ser incluido con la directiva
                     INCLUDE), usado por RPLCOMP o SASM
            .L       Fichero de listado del ensamblador del Saturno
            .LR      Fichero de listados generado por SLOAD
            .M       Fichero de control de SLOAD
            .MN      Fichero de control de MAKEROM
            .O       Fichero de cdigo objeto del Saturno (con la cabecera
                     del Saturno)
            .OL      Fichero de salida del Cargador
            .S       Fichero fuente en RPL

      Para crear un objeto biblioteca completo se usan una serie de ficheros
      fuentes en RPL interno. Ya que eventualmente habr implicados un gran
      nmero de ficheros, se usar un ejemplo ver todo el proceso. El objeto
      biblioteca del ejemplo contendr dos palabras de usuario, que sern
      absurdamente sencillas de modo que se fije la atencin en la estructura
      de los ficheros. La estructura de los ficheros, en este ejemplo, es ms
      complicada de lo necesario, sin embargo la intencin es ilustrar una
      estructura adecuada para aplicaciones ms complicadas.

      En este ejemplo se usarn las letras prefijo GE para diferenciar la
      "biblioteca de geometra" de otros proyectos y para usarlas de prefijo
      en los nombres de las rutinas internas de la biblioteca.

      Este es el fichero por lotes (.BAT) que construye la biblioteca
      ejemplo:

            RPLCOMP GEUSER.S GEUSER.A GEUSER.EXT
            SASM GEUSER

            RPLCOMP GEMAIN.S GEMAIN.A GEMAIN.EXT
            SASM GEMAIN

            RPLCOMP GESUBS.S GESUBS.A GESUBS.EXT
            SASM GESUBS

            RPLCOMP GECFG.S GECFG.A GECFG.EXT
            SASM GECFG

            MAKEROM GE.MN GE.M
            SASM GEHEAD
            SASM GEHASH
            SASM GEEND

            SLOAD GE.M
            SLOAD -H G.M








                                   -4-











      El ejemplo contiene dos palabras, ACONE y VCONE. Los ficheros que se
      usan para construir el objeto biblioteca son:

            Grupo 1
            ----------
            GEROMID.H      Fichero "include" con el ID ROM
            GEEXTDEC.H     Fichero "include" con las declaraciones externas

            Grupo 2
            ----------
            GECFG.S        Cdigo de la configuracin de la biblioteca
            GEUSER.S       Palabras de usuario
            GEMAIN.S       Destinos de los despachos (envos) de las palabras
                           de usuario
            GESUBS.S       Subrutinas

            Grupo 3
            ----------
            GE.MN          Fichero de entrada de MAKEROM
            G.M            Fichero de control del Cargador (SLOAD)

            MAKEGEO.BAT    Fichero "por lotes" para hacerlo todo

      N.T.> ID viene de  ID_entificador

      Los ficheros del grupo 1 son muy importantes. El primer fichero,
      GEROMID.H, contiene una instruccin xROMID que le dice al compilador
      RPL que nmero de biblioteca se va a usar y una asignacin del ID ROM
      en ensamblador que se usar en el cdigo fuente de configuracin:

         *  Fichero "include" del ID ROM de la Biblioteca Geometra. Este 
         *  fichero se debe incluir en todos los mdulos fuentes. Los nmeros
         *  del ID de Biblioteca en este fichero se expresan en hex.

         *** OBSERVA QUE HAY DOS ENTRADAS QUE HAY QUE CAMBIAR SI 
         *** CAMBIA EL ID DE BIBLIOTECA

         xROMID 2FC

         ASSEMBLE

         GEROMID EQU #2FC

      Este fichero se incluye en cada fichero fuente RPL - aquellos ficheros
      que terminan con la extensin ".S". Si se va a cambiar el idrom, solo
      se necesita editar este fichero para efectuar un cambio completo del
      idrom (despus de recompilar y ensamblar todo, naturalmente). Aqu
      sera til una utilidad "make" (hacer).











                                   -5-











      El segundo fichero del grupo 1, GEEXTDEC.H, contiene las declaraciones
      externas.

               TITLE Declaraciones Externas de Geometra
         *****************************************************************
         * Fichero de declaraciones externas de la Biblioteca Geometra.
         * Este fichero se debe incluir en todos los mdulos fuentes. Estas
         * declaraciones externas se listan en orden alfabtico, pero no hay 
         * ninguna exigencia acerca de la ordenacin.
         *****************************************************************

         EXTERNAL GEDoACone
         EXTERNAL GEDoVCone
         EXTERNAL GEtimesPI

      Cada rutina en los ficheros fuentes RPL se deben declarar con NULLNAME,
      de modo que el compilador generar una llamada puntero ROM (llamada
      XLIB) para esa rutina en vez de una llamada-por-direccin (llamada del
      sistema). Los nombres pueden ser de hasta 11 caracteres. Este fichero
      se incluye en cada fichero fuente RPL. Centralizando las declaraciones
      externas en un fichero, no se corre el riesgo que a las llamadas entre
      ficheros les falte alguna declaracin externa.





































                                   -6-











      Los ficheros fuentes en el grupo 2 de arriba contienen el cdigo de
      configuracin, las palabras de usuario y el resto del cdigo de la
      aplicacin. Observa que cada fichero del grupo 2 "INCLUYE" (de INCLUDE)
      ambos ficheros del grupo 1.

      El cdigo de configuracin contiene una etiqueta que no es nula
      (NULLNAME), porque est referenciada por una direccin relativa en la
      cabecera del fichero GEHEAD.S, que se discutir ms abajo. El cdigo de
      configuracin se ejecuta como parte de una serie de acontecimientos que
      se dan cuando se realiza una Parada del Sistema:

               TITLE Configuracin de la Biblioteca Geometra

         INCLUDE GEROMID.H
         INCLUDE GEEXTDEC.H

         *****************************************************************
         * Aade la PARTE ROM (ROMPART) de la Biblioteca Geometra al
         * SYSRAMROMPAIR. Se usa la siguiente construccin de un entero
         * binario para permitir el uso de la asignacin GEROMID definida
         * en GEROMID.H.
         *
         * NOTA: La etiqueta GEcfg solo se referencia mediante una direccin
         * relativa en el fichero de la cabecera GEHEAD de modo que se hace
         * un "NAMELESS" (SinNombre). Si se fuera a referenciar desde un
         * secundario entonces sera necesario cambiarla a un "NULLNAME" de *
modo que la referencia se hara mediante un puntero rom.
         *****************************************************************

         ASSEMBLE
         =GEcfg
         RPL
         ::
           DOBINT GEROMID
           XEQSETLIB             ( autounin ) = (autoattach)
         ;























                                   -7-











      Las palabras de usuario estn reunidas en un fichero, en este caso
      GEUSER.S:

                 TITLE Palabras de Usuario de la Biblioteca Geometra

         INCLUDE GEROMID.H
         INCLUDE GEEXTDEC.H

         *****************************************************************
         * El mdulo de usuario contiene los "xNames" - las palabras de
         * usuario. Estas sern visibles al usuario. El nibble que precede a
         * cada xName le dice al analizador (parser) que no es un algebraico.
         * Observa que las palabras de usuario se especifican con la
         * directiva del compilador "xNAME".
         *****************************************************************
         ASSEMBLE
                 CON(1)  8
         RPL
         xNAME ACONE
         ::
           CK2&Dispatch REALREAL ( real real ) GEDoACone
         ;
         *****************************************************************
         ASSEMBLE
                 CON(1)  8
         RPL
         xNAME VCONE
         ::
           CK2&Dispatch REALREAL ( real real ) GEDoVCone
         ;
         *****************************************************************

      No hay ninguna exigencia que todas las palabras de usuario residan en
      un mismo fichero, pero hay una ventaja. Primero, las palabras de
      usuario (denotadas con una declaracin xNAME en vez de una NULLNAME)
      aparecern en el men de la biblioteca en el orden en que las encuentra
      la herramienta MAKEROM. En segundo lugar, colocando todas las palabras
      de usuario en un solo fichero controlas su orden y evitas recompilar el
      cdigo "check and dispatch" (comprueba y despacha/enva) si solo se
      cambian otras partes del cdigo.



















                                   -8-











      Los destinos de los despachos (envos) de las palabras de usuario
      pueden estar en uno o ms ficheros, a gusto del desarrollador. En este
      ejemplo, el fichero GEMAIN.S contiene los destinos de los despachos de
      las palabras de usuario.

                 TITLE Mdulo Principal de la Biblioteca Geometra

         INCLUDE GEROMID.H
         INCLUDE GEEXTDEC.H

         *****************************************************************
         * El mdulo principal contiene los destinos de los despachos de las
         * palabras de usuario. Cada rutina se nombra con una directiva del 
         * compilador NULLNAME y tiene su correspondiente entrada en el 
         * fichero de declaraciones externas.
         *****************************************************************
         NULLNAME GEDoACone ( %radio %altura --> %rea )
         * Calcula el rea de un cono dados su radio y su altura
         ::
           DUP %* OVER DUP %*            ( r h^2 r^2 --> )
           DUPROT %+ %SQRT               ( r r^2 SQRT[r^2+h^2] --> )
           ROT GEtimesPI %*              ( r^2 PI*r*SQRT[r^2+h^2] --> )
           SWAP GEtimesPI %+             ( %rea )
         ;
         *****************************************************************
         NULLNAME GEDoVCone ( %radio %altura --> %volumen )
         * Calcula el volumen de un cono dados su radio y su altura
         ::
           OVER %* %*
           GEtimesPI %3 %/
         ;
         *****************************************************************


      El fichero GESUBS.S contiene una rutina comn a los dos destinos de
      despachos de las palabras de usuario:

                 TITLE Mdulo de Subrutinas de la Biblioteca Geometra

         INCLUDE GEROMID.H
         INCLUDE GEEXTDEC.H

         *****************************************************************
         * El mdulo principal contiene las subrutinas para las palabras
         * de usuario. Cada subrutina se nombra con una directiva del
         * compilador NULLNAME y tiene su correspondiente entrada en el 
         * fichero de declaraciones externas.
         *****************************************************************
         NULLNAME GEtimesPI ( % --> %*PI )
         * Multiplica el nmero real por PI
         ::
           %PI %*
         ;
         *****************************************************************





                                   -9-











      El programador experimentado observar que el uso de esta subrutina en
      el fichero GESUBS.S crea ms gasto del necesario - el ejemplo aqu es
      para enfatizar las estructuras de los ficheros.

      Cuando se compilan los ficheros fuente con RPLCOMP, es importante estar
      seguros que se generan las declaraciones externas. Por ejemplo, compila
      los ficheros fuentes como sigue:

                      RPLCOMP GEUSER.S GEUSER.A GEUSER.EXT

      Los ficheros del grupo 3 son ficheros de control para las herramientas
      MAKEROM y SLOAD. La herramienta MAKEROM lee el fichero GE.MN y genera
      un nuevo fichero de control del Cargador, GE.M. MAKEROM se invoca as:

                        MAKEROM <fich_entrada> <fich_salida>

      En este ejemplo, la invocacin sera:

                               MAKEROM GE.MN GE.M

      Echmosle una cuidadosa mirada al fichero de entrada de MAKEROM GE.MN:

         TITLE Biblioteca Geometra
         OUTPUT GE.O
         LLIST GE.LR
         CONFIGURE GEcfg
         NAME GELIB :Geometry Libr
         ROMPHEAD GEHEAD.A
         REL GEUSER.O
         REL GEMAIN.O
         REL GESUBS.O
         REL GECFG.O
         TABLE GEHASH.A
         FINISH GEEND.A
         END

      La primera lnea contiene un comando de ttulo para los ficheros de
      listado. El comando OUTPUT dirige la salida del cdigo del Saturno al
      fichero GE.O. El comando LLIST dirige el correspondiente listado del
      informe generado por el cargador al fichero GE.LR. El comando CONFIGURE
      referencia la etiqueta en el cdigo de configuracin (fichero GECFG.S).
      El comando NAME va seguido por el texto de la etiqueta para la
      biblioteca. Este texto aparece en dos lugares:


         +  Una etiqueta de men en el men de la biblioteca. En concordancia
            con otros nombres de biblioteca, el nombre debera ser lo
            suficientemente corto para caber en una etiqueta de men, seguido
            por un espacio y cualquier texto que quieras.

         +  En la pantalla de la HP 48 cuando pulsas [izquierda] [LIBRARY] y
            luego [izquierda] [REVIEW]







                                   -10-











      Las bibliotecas de la Tarjeta de la Biblioteca de Ecuaciones usan cinco
      letras, seguidas de un espacio, dos puntos y texto y este ejemplo sigue
      ese modelo:

               EQLIB :Equation Libr
               PRTBL :Periodic Table
               COLIB :Constants Libr
               FIN   :Finance
               MES   :Mult Eqn Solver
               UTILS :Utilities
               GELIB :Geometry Libr

      Es importante conservar el orden de los comandos, en particular las
      posiciones relativas de los comandos ROMPHEAD, REL, TABLE y FINISH.

      El comando ROMPHEAD especifica el nombre del fichero cabecera que
      generar MAKEROM. Los comandos REL listan todos los mdulos de salida
      que has creado compilando y ensamblando los fichero fuentes RPL. Los
      comandos TABLE y FINISH especifican el fichero de la tabla "hash" y los
      fichero de "parte_rom-fin" que se crearn con MAKEROM.

      Los tres ficheros generados por MAKEROM se deben ensamblar antes del
      siguiente paso. Los ficheros generados en este ejemplo son GEHEAD.A,
      GEHASH.A y GEEND.A

      Este es el fichero de control del cargador GE.M generado por MAKEROM:

         TITLE Geometry Library
         OUTPUT GE.O
         LLIST GE.LR
         **CONFIGURE GEcfg
         **NAME GELIB :Geometry
         **ROMPHEAD GEHEAD.A
         REL GEHEAD.o
         REL GEUSER.O
         REL GEMAIN.O
         REL GESUBS.O
         REL GECFG.O
         ** No se puedo abrir GECFG.ext
         **TABLE GEHASH.A
         REL GEHASH.o
         **FINISH GEEND.A
         REL GEEND.o
         END

      No hay ninguna rutina externa en GECFG.S, de modo que no se cre un
      fichero externo. El mensaje "No se pudo abrir GECFG.ext" es por
      consiguiente inofensivo.











                                   -11-











      Ejecutando SLOAD con el nuevo fichero de control del cargador GE.M se
      produce una parte_rom que est lista para "linkarla" con las rutinas
      internas de la HP 48. Este ltimo paso se consigue con otro fichero de
      control del cargador, G.M:

         TITLE Geometry Library
         OUTPUT GEOLIB
         OPTION CODE
         LLIST GEOLIB.LR
         SUPPRESS XR
         SEARCH \INCLUDE\ENTRIES.O
         REL \INCLUDE\BINHD.O
         REL GE.O
         CK LIB2FC SYSEND2FC

      Cuando se invoca SLOAD con este fichero de control, es importante usar
      la opcin -H en la lnea de comandos. Esto asegura que se generar un
      fichero de cdigo y no un fichero objeto del Saturno (que incluye una
      cabecera y una tabla de smbolos). El comando SEARCH instruye al
      cargador que lea las entradas del sistema HP 48 de modo que se rellenen
      las referencias a las rutinas internas. El comando REL para el fichero
      BINHD.O es el comando para incluir el cdigo binario para la
      transferencia del fichero. La parte_rom se rellena a continuacin y el
      ltimo comando rellena el checksum (suma de comprobacin) de la
      biblioteca.

      La fuente de la cabecera binaria de transferencia no es demasiado
      compleja:

               NIBASC  /HPHP48-A/

      Ensambla el fichero y coloca el fichero BINHD.O resultante en un lugar
      adecuado para incluirlo en tus proyectos.

      La salida de la carga final, en este caso el fichero GEOLIB, esta lista
      ahora para transferirlo a la HP 48.

      Garantizar un comportamiento adecuado de una biblioteca en todos los
      puertos puede ser engorroso. Cuando se use una herramienta "make" para
      manejar las recompilaciones, las dependencias en el fichero "make" son
      tales que cualquier cambio en el ID de la biblioteca o en las
      declaraciones externas obligan a una recompilacin de todos los
      ficheros fuente de la biblioteca, para asegurar que todas las
      referencias se compilan como punteros rom con el ID de biblioteca
      adecuado. Cada vez que se aade una nueva rutina, aade las
      correspondientes declaraciones externas a los ficheros externos.

      La manera ms rpida de verificar la independencia de la direccin es
      mirar en el fichero .lr (en este caso, GE.lr). Una referencia a una
      rutina de la biblioteca que es independiente de la direccin tendr dos
      direcciones despus de su nombre en la referencia cruzada: una para la
      definicin de la rutina (donde est el NULLNAME) y una para su entrada
      en la tabla "link".






                                   -12-