MPSIM Software Simulator Preface MPSIM is a discrete-event simulator designed to imitate operation of Microchip Technology's PIC 16C54, 16C55, 16C56, 16C57, and to provide core simulation of the PIC 16C71 and 16C84 microcontrollers. It is a tool that has been created to assist the user in debugging software that will use any of these parts. A discrete-event simulator, as opposed to an in-circuit emulator, is designed to aid in the debugging of the general logic of your software. The MPSIM discrete-event simulators allows the user to modify object code and immediately re-execute, inject external stimuli to the simulated processor, and trace the exectution of the object code. A simulator differs from an in-circuit emulator in three important areas: cost, I/O timing, and execution speed. The cost of the debugging tool may be an issue with some developers. For this reason, Microchip Technology has developed this simulator to be a cost-effective tool for debugging application software. MPSIM does not require any external hardware to the PC, which keeps the cost at a minimum. External timing in MPSIM is processed only once during each instruction cycle. Transient signals, such as a spike on MCLR at Q2 will not be simulated but may be caught by an in-circuit emulator. In MPSIM, external stimulus is injected just before the next instruction cycle execution. The execution speed of a discrete-event simulator is several orders of magnitude less than a hardware-oriented solution. Users may view slower execution speed as a handicap or a blessing. Some discrete- event simulators are unacceptably slow. MPSIM however, attempts to provide the fastest possible simulation cycle. ------------------------------------------ Chapter 1 - Introduction MPSIM is a discrete-event simulator designed to aid you in debugging your software applications for Microchip Technology's PIC 16C5X and 16CXX microcontrollers. Whether you are an experienced user or a beginner, we strongly suggest that you read this chapter first since it provides information about: ù Installing MPSIM ù 16CXX support ù Customer support information. If this is your first time using MPSIM we also suggest that you go through the tutorial provided in chapter 3. This tutorial introduces all files that are used or generated by the simulator and provides a good introduction to some of the most widely-used commands. Installing MPSIM MPSIM requires an IBM PC or compatible running DOS version 3.0 or later. The PC needs a 31/2 inch floppy disk drive and at least 256K main memory. We recommend a hard disk with at least 5 MB of available space. ù On the PC, create a new directory for the MPSIM software: MKDIR SIM ù Copy all the files on the MPSIM diskette into the above directory: COPY a:\ After loading the software, MPSIM is ready to run. Terminology Breakpoints Source code locations where you want the code to cease execution. Current Program Counter (CPC) The address in the loaded program at which execution will begin or resume. Disassembler Converts modified object code back into assembly- language code when a listing file wasn't loaded. Thus, mnemonic information can display even when you have made changes. Prescaler Used to determine the ratio between actual cycles and the RTCC or WDT. The OPTION register determines whether the prescaler affects the RTCC or the WDT, and also the ratio. Step A single executable instruction. You can single- step through a program by executing one instruction at a time with the SS command. A stimulus file can inject values into specified data areas at specified steps. See section 4.5.2. Symbols Alphanumeric identifiers such as labels, constant names, bit location names and file register names. MPSIM understands both explicit data/addresses and symbols. Trace Recorded execution of a specified number of steps from the CPC, the instructions within a specified memory range or instructions that access a specified register. When you trace the instructions, they always display on-line. If you previously opened a trace file and have not closed it, MPSIM also appends the trace to the file. View screen The portion of your monitor that dynamically displays the values in specified data areas. It is seven lines line. The V command creates a view screen; the AD command adds data areas to the display; the DV command deletes data area from the display; and the NV command deletes all data areas from the view screen. 16CXX Support Version 4.1 or greater of MPSIM now provides core simulation of the PIC 16C71 and 16C84. The peripherals of the 16CXX family, the on-chip A/D converter on the 16C71 and the EE memory on the 16C84 are not implemented. However, MPSIM 4.X does support all interrupts, including writing to EE memory and end of A/D conversion. The following is a list of the four possible interrupts: RTCC overflow from 0xFF to 0x00 PORT RB interrupt INT interrupt EEPROM write (PIC 16C84 only) or A/D conversion complete (PIC 16C71 only) Note that because MPSIM provides "core" simulation of the 16CXX family, the write to EEPROM memory and the A/D conversion do not take place, although the interrupt that can be generated upon their completion has been implemented. In other words, there will be no result in the ADRES register of the 16C71 at the end of an A/D conversion. However, if the interrupt mask bit for an A/D conversion is set prior to conversion, an interrupt will occur when the A/D "conversion" has been completed. When using the simulator for the 16C71 and 16C84, it is important to remember to set the processor type before beginning simulation since the default processor type for MPSIM is the PIC 16C55, which uses the 12 _ bit opcode. If the processor type is not selected before simulation, MPSIM will assume that it is simulating the 16C5X and will either not recognize some of the opcodes and will generate "bad opcode" messages, or will execute incorrect instructions. Also, the stack size will be smaller and the reset vector will not be at zero. Customer Support If you have any questions about MPSIM, Appendix A provides a troubleshooting guide that contains some common error messages and their possible causes. If you still cannot find the answer, contact the Microchip Bulletin Board Service or the sales office nearest you. Information and telephone numbers are presented in Appendix C and on the last page of the manual. ----------------------------------------------- Chapter Two - The MPSIM Environment Chapter Two provides an introduction to the MPSIM debugging environment. It describes all data areas that can be simulated and presents general information about using the simulator. This chapter is highly recommended for first-time users. The following topics will be covered: ù Layout of the User Interface ù I/O Pins, Registers, and the Stack ù Files Used and Generated by MPSIM ù Object-Code Formats ù Invoking MPSIM User Interface The user interface has three areas: the title line, the view screen and a command entry/display region. The title line remains in a fixed location at the top of the screen and lists the current object file, the radix, the MPSIM version, the controller being simulated, cycle steps and elapsed time. The view screen displays user selected pin and register values. This area is created by the user typically through an initialization command file. The command entry/display region occupies the remainder of the screen. Use this area to enter commands; MPSIM enters any responses to a command on the line or lines immediately following the command. To invoke MPSIM, enter the following command at the DOS prompt. MPSIM The `%' is MPSIM's prompt. Enter an object code filename. If you do not specify the .OBJ extension, MPSIM will assume it. The default file format for the simulator is INHX16. Any other format can be used, but must be specified. For more details, see chapter 5, MPSIM commands or Chapter 3, Tutorial. %LO filename [FORMAT] I/O PINS, Registers and the Stack I/O Pins Below is a list of viewable and modifiable pins and registers for the PIC 16CXX and 16C5X microcontroller families. For a more detailed specification of each data area, please refer to the data sheet of the microcontroller in question. PIC16C54/56 PIC16C55/57 PIC16C71/84 Port A RA0-RA3 RA0-RA3 RA0-RA3 Port B RB0-RB7 RB0-RB7 RB0-RB7 Port C N/A RC0-RC3 (57) N/A MCLR MCLR MCLR RTCC RTCC RTCC Pin Signals At the end of each instruction all pins are checked for possible input or output. If the RTCC pin is set, the RTCC register increments in accordance with the prescaler. If the MCLR pin is cleared, MPSIM sets registers to the following values: F2 to Reset Vector OPTION register to 0xFF I/O status registers to 0xFF The I/O TRIS status register bits determine how MPSIM manipulates the port and file register bits. The IOA, RA0- RA3 and F5 registers work together; the IOB, RB0-RB7 and F6 registers work together; and the IOC, RC0-RC7 and F7 registers work together. For I/O TRIS status register bits that are set, MPSIM reads the corresponding port bit into the corresponding file register bit. For I/O TRIS status register bits that are cleared, MPSIM writes the corresponding file register bit to the corresponding port bit (pin). Registers MPSIM simulates all registers in both the PIC 16CXX and 16C5X families. These microcontrollers contain up to 80 registers, of which as many as 72 are special purpose. The following two tables list all file registers and their purpose for the 16C5X and 16CXX. 16C5X File Registers Register Name Function W Working Register F0 Indirect address pointer register F1 RTCC Register F2 Program Counter F3 Status Register F4 File Select Register F5 I/O Register (Port A) F6 I/O Register (Port B) F7 I/O Register (Port C)-PIC 16C57 General Purpose Register for PIC 16C54/55/56 F8 - F1F General purpose registers-Note that this syntax assumes a default radix of hexadecimal. The number following the F must be in the current radix. F20-F7F General purpose registers for the PIC 16C57 only IOA I/O Tris status register for Port A IOB I/O Tris status register for Port B IOC I/O Tris status register for Port C OPT Prescaler assignment, signal source and signal code 16CXX FileRegisters Register Name Function W Working Register F0, F80 Indirect address pointer register F1 RTCC Register F2, F82 Program Counter F3, F83 Status Register F4, F84 File Select Register F5 I/O Register (Port A F6 I/O Register (Port B F7, F87 Unimplemented - Read as 0's F8 ADCON0 in the PIC16C71 EEDATA in the PIC16C84 F9 ADRES in the PIC16C71 EEADR in the PIC16C84 F0A, F8A PCLATH F0B, F8B Interrupt Control Register F0C-F2F General-Purpose Registers F30-F7F Unimplemented - Read as 0's F81, OPT Prescaler assignment, signal source and signal code IOA, F85 I/O Tris Status Register for PortA IOB, F86 I/O Tris Status Register for PortB F88 ADCON1 in the PIC16C71 EECON1 in the PIC16C84 F89 ADRES in the PIC16C71 EECON2 in the PIC16C84 F8C-FAF Registers mapped into Page 0 Hardware Stack Push The CALL instruction pushes the CPC value + 1 to the top of the stack and loads the CPC with the address of the subroutine being called. If the number of CALL instructions exceeds the depth of the stack, MPSIM will issue a "STACK OVERFLOW" error message when executing or single- stepping through code. In the PIC 16C5X family, the CALL instruction is the only instruction that causes an address to be pushed to the stack. The PIC 16C71 and PIC 16C84 however, support interrupts. When an interrupt occurs, the CPC value + 1 is pushed to the stack and the CPC is loaded with the address of the interrupt vector (0x004). The same error message will also be generated if too many addresses are pushed to the stack when MPSIM is executing or single-stepping through aprogram. Pop RETLW instructions in the 16C5X and RETLW, RETURN and RETFIE instructions in the 16CXX instruction set remove or "pop" the last address pushed to the stack and loads its value into the CPC. If an attempt is made to pop more values than the stack contains, MPSIM will issue a "STACK UNDERFLOW" error message when executing or single-stepping through the program. Files Used and Generated By MPSIM MPSIM uses or creates the following I/O files. ù Command file ù Stimulus file ù Journal file ù Listing file ù Input object file ù Output object file ù Symbol file The following sections describe each of these files. Command File Command files are text files containing MPSIM commands. These MPSIM commands are executed with the GE command. Two special command files,MPSIM.INI and MPSIM.JRN, perform initialization tasks automatically and repeat the entire previous MPSIM session, respectively. Initialization File When you execute MPSIM, it automatically performs the MPSIM commands in MPSIM.INI. Common commands in this file might create a standard view screen and/or initialize data areas. Create a MPSIM initialization file with any word processor or text editor. Write an ASCII text file containing the MPSIM commands you want to perform at the beginning of every MPSIM session. Name this file MPSIM.INI. For example, you can set the view screen and the radix. Figure 5.2a lists an example initialization file and figure 5.2b shows the resulting view screen. Journal File If you want to re-execute the most recent MPSIM session, LJ retrieves a list of the commands performed during the previous MPSIM session from MPSIM.JRN. This file is automatically created each time MPSIM is invoked. If you want to retain a journal file, copy it to another filename before re-entering MPSIM. The first time you re-enter MPSIM, the journal file is the same as you copied. However, when you exit via Q or AB, the commands from this MPSIM session will over-write the journal file. Thereafter, you can access the copied file with GE. As with all modern CAD/CAE tools, the concept of journal files is carried throughout MPSIM. That is, any command entered by the user is automatically stored in a journal file (named MPSIM.JRN). The journal file remains in the user's default directory regardless of the termination method (Quit or ABort). The LJ command loads and executes the journal file created during the previous simulator session. However, it doesn't store the commands from the previous journal file in the current journal file. Performing either the Q or AB command removes the previous journal file! The current MPSIM session commands are written over the previous journal file. Stimulus File This file allows you to schedule bit manipulation by forcing MPSIM to drive given pins to given values at a specified input step. This scheduling is via a text file called a stimulus file. The stimulus file can contain up to 232 steps (approximately 2 billion), and can force any pin to any value at any input step during program execution. The ST command reads the stimulus file into MPSIM. When you execute the .OBJ file with E, each time it looks for input, it reads the next step in the stimulus file. The first line of stimulus file always consists of column headings. It lists first the word "STEP," followed by the pins that are to be manipulated. The data below STEP represents the object file's input request occurrence. The data below each pin name is the input value. You may enter comments at the end of a line by preceding it with an exclamation mark (!). The following example illustrates the stimulus file format: STEP pin 1 pin 2 ! These are node names 8 1 0 ! followed by values 16 0 1 24 1 0 Other notes on the format of stimulus file: The steps in the stimulus file must be decimal, regardless of the radix in which you run your simulation The number of spaces separating data tokens is irrelevant Backslash (\) is a continuation mark at the end of a line and indicates that the following line continues the statement from the current line Step RTCC RA3 RA2 RA1 RA0 ! Column Headings 3 0 0 1 0 0 ! Stimulus before cycle 3 4 1 0 1 0 1 ! Injected before cycle 4 9 1 1 0 1 0 ! Injected before cycle 9 10 0 1 0 1 1 ! Injected before cycle 10 15 0 0 0 0 0 ! Injected before cycle 15 16 1 0 0 0 1 ! Injected before cycle 16 Files Generated by the Assembler Listing File The listing file contains the source code the assembler uses to create the object code being simulated. To display the source code throughout simulation, read in the listing file with the LO command. Otherwise, MPSIM uses the disassembler. Input Object File The input object file contains the object code generated by the assembler. The LO command reads an object file directly into program memory. The object code format can be PICES, 8-bit Intel Intellec hexadecimal or 16-bit Intel Intellec hexadecimal. The default format is INHX16. Output Object File At any time during simulation, the contents of the program memory can written to an external file with the O command. The object code format can be PICICE, INHX8S, INHX8M or INHX16. Symbol File The assembler generates the symbol file and contains a collection of symbols used in the source code. This file is used for symbolic debugging, and is automatically loaded when the LO command is used. The RA command clears the symbol file, and restores all original values. Trace File If you open a trace file with the TF command and later trace execution, MPSIM writes the specified trace into the trace file as well as displaying the trace on- line. Object Code Formats The simulator is capable of reading or generating four different object code formats as dictated by the O and LO commands: PICICE, INHX8S, INHX8M and INHX16. The default object-code format that the simulator recognizes is INHX16, but any file format can be loaded by specifying the format when using the LO command. For example: LO Myfile INHX8S will tell the simulator to load myfile.obh and myfile.obl. (The two files necessary for INHX85 format.) Similarly, modified object code can be saved to disk in any format by using the following command: O Myfile INHX8M The file that has been loaded into memory in any format will now be saved as a file in INHX8M format. -------------------------------------------- Chapter 3: Tutorial This chapter provides an introduction to MPSIM, the discrete-event simulator for Microchip Technology's PIC 16C5X and PIC 16CXX families of microcontrollers. It also presents a step-by-step tutorial through a sample program, SAMPLE.ASM. The tutorial is intended to familiarize you with the simulator and to provide an introduction to some of the most commonly used commands. The source code for SAMPLE.ASM and the other files used in the tutorial are available on your master disk, and can also be found in Appendix ? at the end of the manual. If you do not have soft copies of the files for the tutorial, they can be created with any ASCII text editor. It is assumed that both MPALC v. 4.x (the PIC 16C5X and PIC 16CXX assembler) and MPSIM v. 4.x have been installed on your hard drive, and that all files used in the tutorial are in your working directory. The program that is used in this tutorial, SAMPLE.ASM, is a software multiplier that takes two 8-bit numbers, "mulplr" and "mulcnd", and places the 16-bit result in "H_byte" and "L_byte". Because this chapter provides some background examples in addition to the tutorial, all steps that are part of the tutorial will have a step number in bold text to the left of the command in the margin. Assemble the Code Before you can begin to use the simulator, you must first assemble SAMPLE.ASM. MPALC generates an object file in INHX8M format by default, but can also produce the following three output formats: INHX16 INHX8S PICICE There are two default settings that the simulator assumes when it loads your code: the file format and the processor type. The default file format for MPSIM is INHX16, but any format that MPALC generates can be loaded into the simulator. The default processor type for MPSIM is the PIC 16C55, which is the same default processor type that the assembler generates. Version 4.0 and greater of MPALC can assemble instructions for two different cores, so it is important to specify the processor being simulated, especially if you are creating code for the 16CXX since the default processor type is for the 16C5X series. The following syntax can be used to specify both the processor type and the output file format when assembling your code: MPALC filename -F format -P processor For this tutorial, we want the output file format to be INHX16 (the default format used by MPSIM), and the processor type to be 16C54. Type the following at the DOS prompt: MPALC sample -f inhx16 -p 16C54 Invoke the Simulator To invoke the simulator, simply type MPSIM at the DOS prompt. Observe the information in the command area and the information that is displayed in the view screen. The data areas appear in the view screen because an initialization file, MPSIM.INI is in your working directory. MPSIM.INI is simply an ASCII file that contains the same commands that appear in the command area. Every time MPSIM is invoked, it looks for a file called MPSIM.INI. If one exists on your working directory, all of the MPSIM commands appearing in that file will be executed, much like a DOS batch file. It is important to understand that an initialization file can be named anything. MPSIM.INI is unique in that it is automatically loaded when MPSIM is invoked. Load the Initialization File Initialization files are very useful because they allow you to choose data areas that you wish to view, display them on the viewscreen, load your program, select the processor being simulated, and create break points-all in one step. In other words, you can invoke MPSIM, load your initialization file, begin debugging, exit MPSIM, and return later, easily setting up the viewscreen the same way that you had it when you quit the program, simply by loading the initialization file. One easy way to create an initialization file is to first invoke the simulator, type in commands that set up your viewscreen, set some break points, and then quit the simulator. When you quit, you will notice that a file "MPSIM.JRN" has been created. This "journal" file contains every command that you executed in the previous session. If the W register, or any other register was added to the viewscreen, the commands implementing this will be saved in the journal file. This file can then be edited using any text editor to remove commands such as "E" (execute) or "Q" (Quit), and then saved under another file name. It is necessary to remove commands such as "E" and "Q" because they will also be executed when you load your ANYTHING.INI file, and the simulator would set up your viewscreen, execute your code, and quit. It is also important to save the journal file under another name before invoking MPSIM a second time. Each time MPSIM is invoked, it overwrites the previous journal file, and if you did not rename the journal file, it will contain all commands executed in the current session. For this example, we will use the initialization file called "SAMPLE.INI". We will load it by using the following command: GE sample.ini MPSIM executes the commands in the following SAMPLE.INI file. LO SAMPLE ST SAMPLE SR X ZP ZR ZT RE P 54 NV AD mulcnd AD mulplr AD H_byte AD L_byte AD count AD portb AD RB7,B,1 AD RB6,B,1 AD RB5,B,1 AD RB4,B,1 AD RB3,B,1 AD RB2,B,1 AD RB1,B,1 AD RB0,B,1 Sample .INI INITIALIZATION File This changes the viewscreen so that it displays the data areas that SAMPLE.OBJ uses, in the most useful format. The viewscreen now contains data areas that can be watched during execution of SAMPLE.OBJ. Load the Object File Notice that the LO command is listed in the SAMPLE.INI file. Because of this, the object file was automatically loaded when SAMPLE.INI was loaded. If the LO command were not in the SAMPLE.INI file, you could load the file by typing in the following: LO sample It is important to realize that because we have assembled the code in the MPSIM default format (INHX16), we do not have to specify the format being loaded. If we had assembled filename in any format other than INHX16, we would have had to load the file in the following way: LO filename format MPSIM loads the named object file, and then looks for a source file. If the file is available, it also loads the symbol table and the listing file. Load the Stimulus File SAMPLE.INI has taken care of loading the stimulus file. You can see in the SAMPLE.INI file that the command: ST sample.sti was executed when the initialization file was loaded. The stimulus file contains values that are to be input to the pins. When you execute the loaded program, at every instruction step specified in the stimulus file, MPSIM retrieves the input data, and injects their values to the pins. STEP RB7 RB6 RB5 RB4 RB3 RB2 RB1 RB0 !PortB Pins 5 0 0 0 0 1 0 0 1 ! 9 x 5 7 0 0 0 0 0 1 0 1 84 0 0 0 0 1 0 1 0 ! 10 x 5 86 0 0 0 0 0 1 0 1 163 0 0 0 1 1 0 1 1 ! 27 x 3 165 0 0 0 0 0 0 1 1 242 0 0 0 1 0 0 0 1 ! 17 x 7 244 0 0 0 0 0 1 1 1 321 0 1 0 0 0 0 0 0 ! 64 x63 323 0 0 1 1 1 1 1 1 SAMPLE.STI Stimulus File The stimulus file for SAMPLE in figure 5.5 writes the multiplier and multiplicand values into simulated I/O port B. Since this port allows up to eight bits of data, the maximum value of the multiplier and multiplicand is 11111111 or 0xFF. If you would like a additional information about the stimulus file, please refer to Chapter Four, "Simulator Environment". Set Up Trace Parameters A trace file is a file that contains executed instructions, timing information, and registers that have been modified. Using a trace file can be very helpful in determining where to inject stimulus and for creating a "hard copy" of the general execution flow of your program. There are five MPSIM commands dealing with traces: TF TA TC TR DX TF Opens and closes a file for writing the traced data, or writes it to the default printer. TA Traces all instructions between two specified addresses TC Traces a specified number of instructions. TR Traces instructions dealing with specified registers and values. DX Displays the current trace parameters Try some of the following exercises. All of the traces in these exercises will be printed to a file. If you would like to try printing your trace to a default printer, substitute "PRN" in place of the trace file name. Exercise 1: Trace the instructions between two labels, CALL_M and MAIN, and print the instructions to a file. The first step is to create the trace file: TF trace1.trc Next, specify the range of the trace. Then, begin tracing the instructions. TA MAIN CALL_M TC Note: Hit any key to interrupt the trace. Exercise 2: Trace fourteen instructions (0x0E instructions) and write the trace to the file TRACE2.trc. Just as in Exercise 1, we will first open the trace file TF trace2.trc Then, we will trace the next fourteen instructions. Note that if the number of instructions to be traced is not specified, the trace will continue until a key is pressed. TC E Note: If you had specified the number of instructions to be executed as "14" instead of "E", twenty steps would have been executed since the radix is set to hexadecimal (the default radix in MPSIM). Exercise 3: Trace all instructions that access F14 when its value is between 0 and 4 This exercise will show you how to trace instructions that deal with specific registers and values. As usual, we will first open the trace file: TF trace3.trc Then, we will trace instructions that access F14 and where the value in F14 is between 0 and 4, (hexadecimal) inclusive. TR F14, 0, 4 Note: File register 14 can be specified as F14 or as 14. Exercise 4: Check the current trace criteria. DX The current trace parameters display in the command entry area of the MPSIM screen. Set Up Break Points Break points are used to artificially stop program execution so that you can review how the data has been manipulated or to see the contents of the Status Register. There are three instructions that deal with break points: DB BC B DB Displays all of the break points currently set. BC Clears one or all of the break points currently set. B Sets a break point. Exercise 1: Initialize the breakpoints by clearing any breakpoints currently set. Enter the following command: BC Exercise 2: Set a breakpoint at MPY_S. Enter the following command: B MPY_S Exercise 3: Set breakpoints at the location where the high byte becomes necessary and at locations where MULPLR is 0. Enter the following commands: B H_byte > 0 B MULPLR = 0 Exercise 4: Review all the breakpoints. Enter the following command: DB Exercise 5: Delete the breakpoint at MPY_S. Enter the following command: BC MPY_S Execute the Object Code In addition to trace, there are three instructions that you can use to execute your code. E SS C E Executes your code until it encounters a break point or you press a key. SS Single-steps through your instructions. That is, it executes one single instruction at the CPC. C Execute, ignoring "n" number of break points. Exercise 1: Execute code until a break point is encountered. E MPSIM executes until it encounters the first break point or until a key is pressed. Watch the values change the W, F3, F6, and F7 registers. Exercise 2: Execute instructions one step at a time. SS The SS instruction causes MPSIM to execute the instruction at the CPC. Pressing at the MPSIM prompt re-executes the last command. Execute a second instruction by pressing again. Do this several times, watching how the values in the W, F3, F6, aregisters change. This command can be used to single-step through your entireprogram to see the data values at each step, and to watch the flow of your program. If you supply an address with the SS command, MPSIM will modify the CPC to the address you specify and then will execute the instruction at that address. Remember that pressing will cause MPSIM to re- execute the same command, so that if you supplied an address with the command, the same address will be executed. Exercise 3: Execute your program and break after the second break point. C 2 MPSIM executes the instruction at the current CPC until the instruction immediately following the second breakpoint. Watch the values change in the W, F3, F6, and F7 registers. Modify the Object Code MPSIM has four types of commands which allow you to modify the object code: search commands locate code that match specified criteria, display/modify commands automatically display specified code and allow you to change it, delete commands eliminate specified code, output commands allow the modified code to be saved to a file. Exercise 1: Search for the next occurrence of F10, and change its contents to 0xFF. SF F10 Now that you see the next occurrence of F4, use the following command to modify its contents: F F10 After you type in the above command, you will see the current contents of register F10, followed by a colon. Type in the value 0xFF, and watch the contents of the file register change. You will see that the contents of "mulplr" will change since the value of "mulplr" is 0x10. Exercise 2: Change the value of the W register to 0x0C W Just as in Exercise 1, you will see the current contents of W displayed on the screen, followed by a colon. Type in 0x0C, and watch the contents of the W register change. Exercise 3: Change the contents of program memory located at the CPC to a NOP. Type in the following: M You will see the contents of program memory displayed in hexadecimal, followed by a colon. Type in a 0 (object code for NOP), and then . Unlike modifying file registers, you will not immediately exit the function. Instead, you will see the contents of the next memory location followed by a colon. You can continue modifying program memory until you are finished. When you are done, type "q". This will get you back to the MPSIM command prompt (%). Exercise 4: Delete program memory between address 2 and 4. Type in the following command: DM 0,4 This function will delete all program memory between 2 and 4 , and will shift up remaining program memory. If you would like to only clear the program memory between two addresses, use the following command: ZM 2,4 All of program memory between addresses 2 and four will now contain zeros (NOP instructions). It will essentially leave a "hole" in program memory. Exercise 5: Remove the modifications made to program memory from the object code in memory. ZP This instruction clears the patch table. All of the modifications made to SAMPLE.OBJ's program memory are removed Exit the MPSIM Session There are two ways of exiting MPSIM: AB Q These commands are identical. You have now been introduced to some of the most commonly-used functions in the simulator, and should have an understanding of how to use them. If you need any additional information about any of the files that the simulator uses or generates, please review the information in Chapter Four. Chapter Six provides a list of all the commands that are available in MPSIM, complete with a detailed description of their functions and syntax. --------------------------------------------- Chapter Four - Functional Categories of MPSIM Commands Chapter Four is intended to be used as a quick way to help locate a PICSIM command by function. All of the commands presented in this chapter have been grouped together according to function instead of alphabetical order. Once the desired command is found, it can be looked up in Chapter Six "PICSIM Simulator Commands" if a more detailed explanation or example is required. All commands have been divided into the following categories: Loading and Saving Inspecting and Modifying -Program Memory -File Registers and Pins -Timers -Display Functions -Patch Table -Symbol Table Executing and Tracing Modifying the View Screen Miscellaneous Commands Loading and Saving The following three commands load and save object code and listing files. LO filename format Load object file filename with format into program memory. MPSIM also loads the source file. LS filename Load filename into internal symbol table. O filename format Write modified object code to filename. Before simulation can begin, use LO to load an object file into program memory. Immediately after loading the object file, MPSIM tries to load the listing file using the same filename and the extension .LST. If MPSIM still can't find the listing file, the source code file cannot be loaded and displayed at breakpoints. Instead, MPSIM disassembles the object code and displays the disassembled instruction. The object file can be any of four different formats INHX8S, INHX8M, INHX16 and PICICE. The default is INHX16 Example: LO SAMPLE.MPO INHX16 After modifications have been made to the program memory, the user may wish the save the corrected object code into an external file. Use the O command to output the object code. Enter the filename including the extension. Example: O SAMPLE1.MPO INHX16 Example: LO SAMPLE.MPL SAMPLE.MPH INHX8S Inspecting And Modifying MPSIM allows user to change the values of any data area or program memory any time during the simulation. Program Memory In the course of testing a program, you may need to modify its instructions. Both the following commands do so. IA address Display/modify program memory at address using symbolic format. M address Display/modify program memory at address using the current radix format. If you use IA, the source code for the address displays, followed by `:' on the next line for the new command. The new command must consist of a valid mnemonic followed by zero or more operands. Each operand must contain a single value or symbol, no expressions will be allowed. MPSIM interprets all values based on the current input radix as set with the SR command. Entering `Q' at the prompt ends the command; entering `-' causes MPSIM to go back and inspect/modify the previous address; entering leaves the instruction alone and continues to the next address. Example: %IA 200 0020 0200 0145 LABEL CLRF F5 ;Clear I/O register for Port A : CLRF 6 0021 0201 0147 CLRF F7 ;Clear I/O register for port C : - 0200 0146 LABEL CLRF 6 : Q After changing the object code, the original source code no longer displays. It is replaced by a disassembled source line. If you use M, the contents of the address display in the same format as the current radix. The prompt `:' immediately follows the data. Place the new value after the prompt, using the current radix. The `-', `Q' and have the same affect as described above. Two additional commands that affect program memory are: IN address,instruction Insert instruction at address in symbolic format. DE address1,address2 Delete program memory from address1 to address2. The IN command places a symbolically formatted opcode at the given address, then displaces values that follow address by one location. The new command must consist of a valid mnemonic followed by zero or more operands. Each operand must contain a single value or symbol, no expressions will be allowed. The DE command deletes the code within the given boundaries then shifts all data in program memory locations greater than the upper boundary down to the lower boundary. Registers Each register can be inspected/modified by using the following commands: F register Display/modify contents of file register W Display/modify contents of W register SC Display/modify processor cycle time SE data_area Display/modify any data_area RE Reset elapsed time and step count Inspect and modify file registers with the F command. The value of the register displays followed by the prompt `:'. Enter the new value after this prompt. Example: %F 3 F3:20:21 (The value of F3 has now been changed to 21.) To inspect and modify the W register the W command is used. Example: %W W:44:00 (The value of W has now been changed to 0.) Inspect and modify the simulated cycle time with the SC command. Example: %SC 2.0:.2 Display and/or modify the value of any other data area (stack,pins,status bits, all registers) with the SE command. Example: %SE OPT OPT:FF:FE Display Functions The display functions are provided to print formatted lists of various program variables in the command/source area on the screen. DR Displays the contents of all registers including W, status and the stack. DM addr1,addr2 Displays the code from address1 to address2. The code displays only in the current radix, not in mnemonics. address1 must be less than address2 and both must be in the valid range of program memory. DI addr1,addr2 Displays the code from address1 to address2. The code displays in both the current radix and mnemonics. address1 must be less then address2 and both must be in the valid range of program memory. You can terminate the DM and DI commands at any time by pressing any key. Example: %DI 0, 3 0000 0020 MOVWF 0 The MOVWF instruction = 2 0001 0063 CLRF 3 The CLRF instruction = 6 0002 0080 SUBWF 0,0 The SUBWF instruction = 8 0003 0069 CLRF 9 The CLRF instruction = 6 %DM 0, 3 0000 0020 0001 0063 0002 0080 0003 0069 Patch Table During the course of simulation, several changes may have been made to the object code in order to achieve the desired results. The patch table keeps track of all changes made by maintaining the original value of the address along with the most recent change. The patch table can then be displayed out in symbolic format to aid the user in making changes to the source code. The following three commands manipulate the patch-table. ZP Clears the patch table and resets it to no patches made. All changes previously made to the object code remain. DP Display all patches in symbolic format. Both the original object code and new code display. RP Restores all patches to their original value and clears the patch table. Clearing Memory and Registers Memory and registers can be cleared quickly by using the following commands. ZM addr1,addr2Zero the program memory from address1 to address2. address1 must less than address2 and both must be valid program memory addresses. ZR Zero all of the file registers (F0 through F31). ZT Zero the elapsed time counter. Clear any of the other data areas with the SE command. Searching Memory It is sometimes desirable to search the program memory for specific instructions or operands. The following three commands search program memory for various patterns and display(?) each line containing that pattern. SI address1,address2,instruction Search program memory from address1 to address2 for any occurrence of instruction. instruction is in mnemonic format. SM address1,address2,m Search program memory from address1 to address2 for any occurrence of the value m. Specify the search criteria in the radix mode, not in mnemonics. SFaddress1,address2,register Search program memory from address1 to address2 for any instruction that accesses file register. Specify the search criteria in the radix mode, not in mnemonics. Example: %SI 0, 20, NOP 0000 0000 LOOP NOP 0006 0000 NOP 001E 0000 NOP %SM 0, 20, 0 0000 0000 0006 0000 001E 0000 Symbol Table The following commands manipulate the symbol table: DS Display symbol table. DL symbol Delete symbol from symbol table GS symbol,value,type Generate symbol with a value of type. type may be file, bit(file), label or literal. See the GS command description for the exact syntax. Example: %DS Symbol Value Type START 0000 L %GS NEWSYM, FF, B Symbol Value Type START 0000 L NEWSYM 00FF B Restore The Restore All command, RA, has the combined effect of restoring the patch table, clearing the symbol table and removing all breakpoints. Execute and Trace The simulator executes in three basic modes, execute until break, single step or trace. In either of these modes you can stop execution at any time by pressing any key. Execution Instructions The E command begins execution at the specified address, or at the CPC if you don't specify an address. The loaded program executes until reaching a breakpoint or until you press any key. If you wish to slow down execution, use the single step instruction, SS. SS executes the single instruction at the specified address or at the CPC if you don't specify an address. Tracing Execution In the trace mode, all addresses meeting certain conditions display as they execute. The conditions may include: A given instruction within address boundaries. Accessing a given register. A given register containing a value between two limits. The following trace parameters maintain trace execution. Register number being traced. Range of register values. Range of addresses to trace. The following commands set up and execute the trace mode. TC #instr Trace the next #instructions. If you omit #instructions, execution continues until MPSIM encounters a breakpoint or until you press any key. TA Sets the upper and lower address trace limits to the full range of program memory. TA addr1,addr2 Sets the lower validation limit for address trace to address1 and the upper address validation limit to address2. TR Sets the address trace to trace any file register. TR reg Sets the address trace to trace the file register. TRreg,min_val,max_val Sets the address trace to trace the file register only if the value of the register is between min_value and max_value. DX Displays the current trace parameters. When in trace mode, the location, opcode, mnemonic, elapsed time, cycle steps and any changed data areas will be displayed when the given conditions are met. Note: F2 and F3 won't display if changed, however, status bits do display. Examples: %DX Address 0000:01FF %TC 2 0002 0000 LOOP NOP | 6.00u 0003 | 0003 0040 TEST CLRW | 8.00u 0004 | Z:1 %TR 4, 0, F %TR 3 %TA 0, 4 %DX Address 0000:0004 F3 0000:01FF F4 0000:000F %TC 40 0004 0020 CALL START | 10.00u 0005| [005,000] Stack contents always display in brackets with the top of the stack to the left. Breakpoints MPSIM allows the user to set up to 512 breakpoints on any valid address. It also allows conditional breakpoints on any of the data areas. When one of these breakpoints is encountered, the current address is displayed in symbolic format and control is returned to the user. The following commands control the breakpoints: B address Set breakpoint at address (symbolic address can be used). B data_area op val Break when data_area matches the condition given by the operator (=,>,<,>=,<=,!=) and value. BC address Cancel breakpoint at address. BC data_area Cancel breakpoint involving data_area. BC Cancel all breakpoints. C #breakpoints Continue execution ignoring #breakpoints breakpoint occurrences. DB Display all active breakpoints. Only one conditional breakpoint is allowed per data area. View Screen The following commands set up and manipulate the view screen. V data_area,radix,#digits This command sets up the view screen. This means that the View command defines the variables (and respective formats) to constantly display on the screen. Once the view screen is set, it remains active until either a NOVIEW command or a View sets up a new view screen. The format of this command is relatively simple. Register or signal s displays in radix mode r with n digits. r defaults to hexadecimal and n defaults to 1. If n is omitted, the number of digits is 1. The radix can be binary, octal, hexadecimal or decimal. NV This command clears the view screen. The same effect can be achieved by re- defining the view screen. AD data_area,radix,#digits This command adds items to the view screen. If one desires to add more display items to the view screen, use the Add command. While this command's format is identical to View, it doesn't destroy the current contents of the view screen, but simply displays additional items as well as the current ones. DV data_area This command simply removes display items from the view screen while leaving the display formatting intact. TY data_area,radix,#digits This command changes the formatting of the existing view screen. s is the signal name (if the designated signal isn't in the view screen, MPSIM gives a warning). The radix can be x, o, d or b and n is the number of spaces to reserve for this variable at the display time. Miscellaneous Commands SR radix This command sets the input/output radix to Octal, heXadecimal or Decimal. The radix will be used on all inputs and outputs with the exception of file register numbers and step counts. P {54|55|56|57|71|84} Choose the appropriate PIC number n. n can be either 54, 55. 56 or 57 for the PIC 16C54, 16C55, 16C56, 16C57, 16C71 or 16C84 respectively. The default is 55. GE filename This command forces MPSIM to get its command stream from an external text file. When end of file is reached, the control is returned to the user interface. All the incoming commands are parsed by the same mechanism as the one supervising the on-line interface thus the syntax should follow the guidelines of this document. If the specified file is not found, the user will be notified. Q This command terminates the dialogue. It prints out one or two summary messages, removes the journal file and exits to the operating system. AB This command aborts the dialogue. It prints out one or two summary messages and exits to the operating system. ST filename Stimulus command allows the user to introduce an event- based stimulus injection into the model. That is, the user may want to inject certain values into certain pins or registers at some point during the simulation. The stimuli are defined in a text file whose format is described in section 4.5.2. H The Help command lists the syntax and a brief summary of each command available in MPSIM. There are several screens of information. Press SPACEBAR to exit, any other key to display the next screen. ---------------------------------------------------- Chapter 5 - MPSIM Commands ****************************************** AB - ABORT SESSION ****************************************** Syntax AB Description The abort command interrupts the PICSIM session and exits. It prints out one or two summary messages, and exits to the operating system. PICSIM retains the journal file. Examples PICSIM Command Result AB PICSIM exits and displays the following message: Elapsed CPU time: h:mm:ss Defaults None. Related Commands The Q command gives the same result. ****************************************** AD - ADD ITEM TO VIEW SCREEN ****************************************** Syntax AD signal{,radix}{,digits} Description The Add command adds a signal or register to the view screen. Optionally, you may specify a radix different from the default and/or the number of digits. While this command's format is identical to View, it doesn't destroy the current contents of the view screen, but simply displays additional items as well as the current ones. Examples PICSIM Command Result AD RTCC Add the RTCC pin to the screen display AD RA0,B Add the RA0 pin to the screen display with binary radix AD MCLR,4 Add MCLR to the screen display with 4 digits AD F3,B,8 Add the F3 register (status) to the screen display with binary radix and 8 digits Defaults Digits defaults to 2. The radix ordinarily defaults to hexadecimal, but you can change this default with the SR command. Radix Digits X 2 B 8 O 3 D 2 Related Commands The V command displays the first signal or register you request. Subsequently, you can add display items with AD or delete them with DV. If you use a V command after AD, V replaces all previous display items on the screen with the named signal or register. The NV command wipes all display items off the screen. The GE command can load an initialization file that sets up the view screen. Thereafter, you can use AD and DVto modify it. Note:When referencing registers for the AD instruction use hex notation. For example, file register 10 would be written as "0A". Example: AD F0A, X, 2 ****************************************** B - SET BREAKPOINT ****************************************** Syntax B [address|pin] {operator value} Description This command sets a breakpoint at the specified address or at the location where the specified pin or register matches the condition set by the operator and the value. You can designate the address either with the explicit numeric location or with a symbol. The operator can be any or the following: = equal > greater than < less than >= greater than or equal <= less than or equal != not equal Examples PICSIM Command Result B LOOP Set breakpoint at label LOOP. B F2 > 80 Break if F2 is greater than 80. Defaults None. Related Commands BC clears breakpoints previously set and DB displays them. Note: When referencing registers for relational instructions use decimal notation. ****************************************** BC - clear breakpoints ****************************************** Syntax BC {address|data_area} Description This command deletes a specified breakpoint, or all breakpoints if you don't specify one by address or data area. Examples PICSIM Command Result BC LOOP Cancel breakpoint at LOOP BC F3 Cancel breakpoint involving the F3 register BC Cancel all breakpoints Defaults None. Related Commands B sets breakpoints and DB displays them. ****************************************** C - CONTINUE EXECUTING ****************************************** Syntax C {n} Description This command continues execution from the CPC. If you specify n, PICSIM ignores the first n breakpoints encountered. Examples PICSIM Command Result C Continue executing, break at the nextbreakpoint. C 3 Continue executing, skip the first three breakpoints found, but break at the fourth. Defaults n defaults to 0. Related Commands B sets the breakpoints, DB displays them and.BC clears breakpoints previously set. ****************************************** DB - DISPLAY ALL BREAKPOINTS ****************************************** Syntax DB Description This command lists all active breakpoints. PICSIM allows only one conditional breakpoint per data area. Examples PICSIM Command Result B LOOP Sets a breakpoint at LOOP B F2 > 80 Sets a breakpoint at the location where F2 >80 DB Displays all breakpoint locations via messages: INFO, Break when (F2 > 0080) INFO, Break on address LOOP Defaults None. Related Commands B sets the breakpoints, DB displays them and BC clears breakpoints previously set. ****************************************** DE - DELETE PROGRAM MEMORY ****************************************** Syntax DE address1 address2 Description This command deletes the information stored between address1 and address2, inclusively. The DE command deletes memory within the given boundaries then shifts those locations in program memory that are greater than the upper bound down to the lower bound. Examples PICSIM Command Result DE 0015 0A10 This command removes the GOTO MAIN statement that causes the application to continuously execute. Defaults None. Related Commands None. ****************************************** DI - DISPLAY PROGRAM MEMORY IN SYMBOLIC FORMAT ****************************************** Syntax DI address1 address2 Description This command displays program memory in symbolic format from address1 to address2. address1 must be less then address2 and both must be in the valid range of program memory. If no address2, I/O lines display at address1. You can terminate DI at any time by pressing any key at the terminal. Examples PICSIM Command Result DI 0, 3 The following messages display: 0000 0020 MOVWF 0 0001 0063 CLRF 3 0002 0080 SUBWF 0, 0 0003 0069 CLRF 9 Defaults None. Related Commands The DM command also displays memory between two specified addresses; however, DM displays the code in the format specified by the current radix rather than in symbolic format. ****************************************** DL - DELETE SYMBOL FROM SYMBOL TABLE ****************************************** Syntax DL symbol Description This command removes the specified symbol from the symbol table. Examples PICSIM Command Result DL MULPLR PICSIM removes "mulplr" from the symbol table. To provide to or obtain data from this data area, you must now use the actual register number, F10. The value on the view screen, since it reads "MULPLR" isn't updated. Defaults None. Related Commands GS creates a symbol and puts it into the symbol table, LS loads a new symbol table, DS displays the current symbol table and RA restores (clears) the symbol table. ****************************************** DM - DISPLAY PROGRAM MEMORY IN RADIX DESIGNATED FORMAT ****************************************** Syntax DM address1 address2 Description This command displays program memory from address1 to address2. The data stored displays in the format designated by the current radix address1 must be less than address2 and both must be in the valid range for program memory. You can terminate DM at any time by pressing any key on the terminal. Examples PICSIM Command Result DM 0, 3 PICSIM displays the memory between locations 0 and 3. The following messages display: 0000 0020 0001 0063 0002 0080 0003 0069 Defaults None. Related Commands The DI command also displays memory between two specified addresses; however, DI displays the code in symbolic format rather than in the format specified by the current radix. ****************************************** DP - DISPLAY ALL PATCHES ****************************************** Syntax DP Description This command displays all patches in symbolic format. Both the original object code and new object code display. Defaults None. Related Commands The M and IA commands modify the object code; .IN adds commands to the object code; DE removes object code; RA and RP restore the patches; and ZP zeros the patches. O writes the modified object code. ****************************************** DR - DISPLAY ALL REGISTERS ****************************************** Syntax DR Description This command displays the contents of all registers including the W and status registers, all flags and the stack. Defaults None. Related Commands The DP, DS and DX commands display other PICSIM data areas and parameters. SE sets any data area's value. W displays and optionally modifies the W register. F displays and optionally modifies a register value. ****************************************** DS - DISPLAY SYMBOL TABLE ****************************************** Syntax DS Description This command displays the symbol table. Defaults None. Related Commands GS creates a symbol and puts it into the symbol table, LS loads a new symbol table, DL removes a symbol from the current symbol table and RA restores (clears) the symbol table. ****************************************** DV - DELETE VIEW SCREEN ITEM ****************************************** Syntax DV data Description This command deletes a signal or register from the view screen display. This command simply removes display items from the view screen while leaving the display formatting intact. Examples PICSIM Command Result DV RTCC Deletes the RTCC from the view screen. Defaults NONE. Related Commands The V command displays the first signal or register you request. Subsequently, you can add display items with AD or delete them with DV. If you use a V command after AD, V replaces all previous display items on the screen with the named signal or register. The NV command wipes all display items off the screen. The GE command can load an initialization file that sets up the view screen. Thereafter, you can use AD and DV to modify it. ****************************************** DW - ENABLE/DISABLE WATCHDOG TIMER ****************************************** Syntax DW {E|D} Description This command enables or disables the watchdog timer, depending or the parameter specified. E enables it; D disables it. Examples PICSIM Command Result DW E Enables the watchdog timer DW D Disables the watchdog timer Defaults None. Related Commands RE resets the elapsed time and step count and ZT zeros the elapsed time. ****************************************** DX - DISPLAY CURRENT TRACE PARAMETERS ****************************************** Syntax DX Description This command displays the current trace parameters. When in trace mode, the location, opcode, mnemonic, elapsed time, cycle steps, and any changed data areas display when the given conditions are met. Examples PICSIM Command Result DX The following message displays: Address 0000:01FF Defaults None. Related Commands The TA, TC and TR commands set the trace parameters. ****************************************** E - EXECUTE PROGRAM ****************************************** Syntax E {address} Description This command executes the program from the optionally specified address or the CPC. The E command begins execution at the specified address or at the current address if no address is specified. The program continues to execute until either reaching a breakpoint or until you press a key. Examples PICSIM Command Result E 0E PICSIM executes SAMPLE.OBJ from the label START until reaching a berakpoint or until you press any key. Defaults None. Related Commands The GO command resets then executes from the start; SS executes the instruction at the CPC or at a specified address. C executes from the CPC to the specified breakpoint occurrence. TA traces execution between specified addresses, and TC traces execution from the CPC for a specifies number of instructions. ****************************************** F - DISPLAY/MODIFY FILE REGISTER ****************************************** Syntax F register Description This command displays and/or modifies the contents of the specified file register. The value of the register displays, followed by the prompt `:'. Place the new value after the prompt. Examples PICSIM Command Result %F 3 The following message displays: F3:20: This shows that the F3 register contains the value `20.' F3:20:21 The F3 register value changes to `21.' Defaults None. Related Commands The SE command can give the same result. DR, TR and ZR display, trace and zero a specified register, respectivelyt. M and IA modify the code at a specified address, which can affect the register's value. ****************************************** GE - GET COMMANDS FROM AN EXTERNAL FILE ****************************************** Syntax GE filename Description This command reads and performs the PICSIM commands in the named ASCII file. This command forces PICSIM to get its command stream from an external text file. After reaching the end of file, control returns to the user. Commands in the text file must conform to the same syntax as commands entered on-line. If PICSIM cannot locate the specified file, an error message displays. Examples PICSIM Command Result GE SAMPLE.INI Reads and performs commands in the file, SAMPLE.INI. Defaults None. Related Commands The V command displays the first signal or register you request. Subsequently, you can add display items with AD or delete them with DV. If you use a V command after AD, V replaces all previous display items on the screen with the named signal or register. The NV command wipes all display items off the screen. The GE command can load an initialization file that sets up the view screen. Thereafter, you can use AD and DV to modify it. ****************************************** GO - RESET AND EXECUTE ****************************************** Syntax GO Description This command resets the PIC then executes the loaded object code. Examples PICSIM Command Result GO Defaults None. Related Commands The E command executes from a specified address or the CPC; SS executes the instruction at the CPC or at a specified address. C executes from the CPC to the specified breakpoint occurrence. TA traces execution between specified addresses, and TC traces execution from the CPC for a specifies number of instructions. ****************************************** GS - GENERATE SYMBOL ****************************************** Syntax GS symbol,value,type{(filename)} Description This command generates the specified symbol with the specified value and type. The type can be file, bit, label or literal. If the type is bit, it is a bit in the specified file. Examples PICSIM Command Result %DS Symbol Value Type START 0000 L %GS NEWSYM, FF, B Symbol Value Type START 0000 L NEWSYM 00FF B Defaults None. Related Commands DL removes a symbol from the current symbol table, LS loads a new symbol table, DS displays the current symbol table and RA restores (clears) the symbol table. ****************************************** H - HELP ****************************************** Syntax H Description This command displays the Help screen, which lists a brief synopsis and syntax for each PICSIM command. Examples PICSIM Command Result H The Help screen, containing command descriptions and syntax displays. Defaults None. Related Commands None. ****************************************** IA - DISPLAY/MODIFY PROGRAM MEMORY(SYMBOLIC FORMAT) ****************************************** Syntax IA address Description This command displays or modifies the program memory at address in symbolic format. The source code for the address displays, followed by the prompt `:' on the next line for the new command. Enter the new command as a mnemonic. It must be syntactically correct. Operands may contain only a single value or symbol; expressions are not allowed. Enter values in the current radix. Entering `Q' at the prompt ends the command; entering `-' causes PICSIM to go back and inspect and/or modify the previous address; entering continues to the next address. After changing the object code, PICSIM no longer displays the original source code. PICSIM replaces it with a disassembled source line. Examples PICSIM Command Result %IA 200 The instruction line at address 200 (in the current radix) displays: 020 0200 0145 LABEL CLRF F5 ;Clear I/O register for port A: : CLRF 6 PICSIM changes thge instruction as specified and displays the next instruction line (address 201): 0021 0201 0147 CLRF F7: : - PICSIM backs up and displays the modified instruction at address 200: 0200 0146 LABEL CLRF 6: : Q PICSIM exits the IA command. Defaults None. Related Commands DE, IN, M. ****************************************** IN - INSERT INSTRUCTION ****************************************** Syntax IN address,instruction Description This command inserts instruction at address. The instruction places an opcode at address then displaces each program memory value after address by one location. instruction must consist of a valid mnemonic followed by zero or more operands. Each operand must contain a single value or symbol, no expressions are allowed. Examples PICSIM Command Result %IN 200, NOP PICSIM inserts a NOP instruction at address 200 (in the current radix). Defaults None. Related Commands DE, IA, M. ****************************************** LJ - LOAD JOURNAL FILE ****************************************** Syntax LJ Description This command loads and executes the journal file commands. These commands are not stored in the journal file recorded from the current session; PICSIM enters only the LJ command. When the journal file contains a program execution command, you must press a key to stop program execution or wait until a breakpoint break occurs; the journal file doesn't record premature execution breaks or exits. Examples PICSIM Command Result % LJ All PICSIM commands entered during the previous PICSIM session execute These commands are not stored in the journal file recorded from the current session. Defaults The default extension is `.JRN'. Related Commands GE, LJ, LO, ST. ****************************************** LJ - LOAD AND EXECUTE JOURNAL FILE ****************************************** Syntax LO filename {format} Description This command loads the specified object file into program memory. After loading the object file, PICSIM attempts to load the listing file using the same filename and the extension `.LST'. If PICSIM cannot find the listing file then all instruction displays will be a disassembly. When found, PICSIM uses the listing file for display throughout simulation. The following is a list of valid formats: INHX8M INHX16 INHX8S PICICE Examples PICSIM Command Result % LO SAMPLE.MPO INHX16 The object, listing and symbol file are loaded into MPSIM. Defaults The default extension is `.OBJ' and the default format is INHX16. Related Commands GE, LJ, LS, ST. ****************************************** LO - LOAD OBJECT FILE ****************************************** Syntax LS filename Description This command loads the specified symbol file into the internal symbol table. If symbolic debugging, the symbol file produced by the assembler must be loaded with the LS command or loaded through the LO command. Examples PICSIM Command Result % LS SAMPLE.SYM PICSIM reads in the symbol file SAMPLE.SYM. Defaults The default extension is `.SYM'. Related Commands GS, DL, DS, RA. ****************************************** LS - LOAD SYMBOL FILE ****************************************** Syntax M address Description This command displays and/or modifies program memory at address. The contents of the address display in the radix designated format, and are followed immediately by a prompt `:'. To change the value at address, place a new value after the prompt. Be sure to enter that value in the current radix. Entering `Q' at the prompt ends the command; entering `-' causes PICSIM to go back and inspect and/or modify the previous address; entering continues to the next address. Examples PICSIM Command Result % M 0005 PICSIM displays the instruction line at address 0005 (as determined by the current radix) in the current radix:% SR O % M 010 PICSIM sets the radix to octal, then displays the instruction line at the label MAIN in octal: Q PICSIM exits the M command. % SR X % M 010 PICSIM sets the radix to hexadecimal, then displays the instruction line at the label MAIN in hexadecimal: : - PICSIM redisplays the instruction line at MAIN: % SR D % M main PICSIM sets the radix to decimal, then displays the instruction line at the label MAIN in decimal. Defaults None. Related Commands IA ****************************************** M - DISPLAY/MODIFY PROGRAM MEMORY (RADIX DESIGNATED FORMAT) ****************************************** Syntax NV Description This command deletes or clears all elements from the view screen. The same effect can be achieved by re-defining the view screen. Examples PICSIM Command Result % NV PICSIM removes all items from the view screen. Defaults None. Related Commands AD, V. ****************************************** O - OUTPUT MODIFIED OBJECT CODE ****************************************** Syntax O filename [format] Description This command writes the contents of program memory, including any modifications to the specified file in the specified format. The program memory contains object code. The following is a list of valid formats: INHX8M INHX16 INHX8S PICICE Examples PICSIM Command Result % O SAMPLE1.OBJ INHX8M PICSIM writes the object code, as modified, to the file SAMPLE1.OBJ in the INHX16 format. Defaults Default output format is the same as the default input format, INHX16 Related Commands None. ****************************************** P - SELECT MICROCONTROLLER ****************************************** Syntax P [54|55|56|57|71|84] Description Use this command to select the PIC microcontroller you want to simulate. Examples PICSIM Command Result %P [54|55|56|57|71|84] PICSIM sets the processor type. Defaults The simulated microcontroller defaults to 55. Related Commands None. ****************************************** Q - QUIT ****************************************** Syntax Q Description This command exits from PICSIM and returns PC control to DOS. PICSIM stores all PICSIM commands entered during this session in the journal file, PICSIM.JRN. The old PICSIM.JRN, if present, is overwritten. Examples PICSIM Command Result % Q PICSIM exits and displays the following message: Elapsed CPU time: h:mm:ss Defaults None. Related Commands AB ****************************************** RA - RESTORE ALL ****************************************** Syntax RA Description This command restores the patch table, clears the symbol table of user defined symbols and removes all breakpoints. Examples PICSIM Command Result % RA PICSIM restores the patch table, clears the symbol tables and removes all breakpoints. Defaults None. Related Commands RP, DL, BC. ****************************************** RE - RESET ELAPSED TIME AND STEP COUNTER ****************************************** Syntax RE Description This command resets the elapsed time and the step count to zero. Examples PICSIM Command Result % RE PICSIM resets the elapsed time and the step count to zeros. Defaults None. Related Commands ZT. ****************************************** RP - RESTORE PATCHES ****************************************** Syntax RP Description This command restores all patches to their original value and clears the patch table. Examples PICSIM Command Result % RP PICSIM restores all patches. Defaults None. Related Commands RA ****************************************** SC - DISPLAY/MODIFY PROCESSOR CYCLE TIME ****************************************** Syntax SC [cyclelength] Description This command displays and/or modifies the microcontroller's simulated cycle time. Examples PICSIM Command Result % SC PICSIM displays the current cycle in æs: 2.0: 2.0:.2 The entry `.2' changes the cycle to .2æs. % SC 2000.0 The cycle length is changed to 2000.0æs or 2.0 ms Defaults The simulated cycle time defaults to 2 microseconds. Related Commands None. ****************************************** SE - DISPLAY/MODIFY DATA AREA ****************************************** Syntax SE data Description This command displays and/or modifies any data area. Examples PICSIM Command Result % SE RA0 RA0:1:0 The following message displays: RA0=1: The value of I/O pin RA0 changes from 1 to 0. Defaults None. Related Commands F, W, ZR. ****************************************** SF - SEARCH PROGRAM MEMORY FOR REGISTER ****************************************** Syntax SF address1, address2, register Description This command searches program memory from address1 to address2 for any instruction that access the specified register. register may be specified in literal, `F' syntax or as a symbol. Examples PICSIM Command Result SF 0, 22, portb PICSIM search all memory from 0 through 22 for instructions that reference the portb register, then displays the lines containing the specified instruction: 0000 0000 main movf portb,W 0006 0000 movf portb,W Defaults None. Related Commands SI, SM. ****************************************** SI - SEARCH PROGRAM MEMORY IN SYMBOLIC FORMAT ****************************************** Syntax SI address1, address2, instruction Description This command searches program memory from address1 to address2 for any occurrence of instruction. instruction is in symbolic format. Full or partial instructions may be specified. Examples PICSIM Command Result % SI 0, 20, CLRF PICSIM searches all memory from 0 through 20 for CLRF instructions, then displays the lines containing the specified instruction: 0000 mpy_S clrf H_byte 0001 clrf L_byte % SI 0, 20, PICSIM searches all movwf count memory from 0 through 20 for MOVWF COUNT instructions, then display the lines containing the specified instruction: 0003 movwf count Defaults None. Related Commands SF, SM. ****************************************** SM - SEARCH PROGRAM MEMORY IN RADIX FORMAT ****************************************** Syntax SM address1, address2, instruction Description This command searches program memory from address1 to address2 for instruction . Specify instruction in the format designated by the radix. Examples PICSIM Command Result % SM 0, 30, C08 PICSIM search all memory from 0 through 20 for the specified instruction, then displays, in the current radix, the lines containing it: 0002 movlw 8 Defaults None. Related Commands SF, SI. ****************************************** SR - SET RADIX ****************************************** Syntax SR [O|X|D] Description This command sets the radix to octal, hexadecimal or decimal. Subsequently, PICSIM expects and uses this radix for all I/O including file register numbers and step counts. Examples PICSIM Command Result % SR O The radix becomes octal % SR X The radix becomes hexadecimal % SR D The radix becomes decimal Defaults None. Related Commands None. ****************************************** SS - EXECUTE A SINGLE STEP ****************************************** Syntax SS [address] Description This command executes a single step located at address. If you don't specify address, PICSIM executes the instruction at the CPC. Pressing at the % prompt re-executes the previous PICSIM command. Thus, by entering SS once and subsequently pressing simply , you can single step through multiple instructions easily. Examples PICSIM Command Result % SS 01FF PICSIM resets the simulator code by executing the reset address (PIC 16C54 and 16C55). % SS PICSIM executes the line of code at the PCP. % SS 20 PICSIM executes the line of code at address 20 (in the current radix). % SS LOOP PICSIM executes the line of code at the label LOOP Defaults None. Related Commands None. ****************************************** ST - READ STIMULUS FILE ****************************************** Syntax ST filename Description This command inserts specified values into specified pins or registers at a specified simulation step or time. The specified values, pins/registers and steps are defined in a text file called a stimulus file. Stimulus can be injected either according to step or time. See instruction `IP' for details. The stimulus file allows you to schedule bit manipulation by forcing PICSIM to drive given pins to given values at a specified input step. The ST command reads the stimulus file into PICSIM. When you execute the .OBJ file with E, each time it looks for input, it reads the next step in the stimulus file. The first line of stimulus file always consists of column headings. It lists first the word "STEP," followed by the pins that are to be manipulated. The data below STEP represents the object file's input request occurrence. The data below each pin name is the input value. You may enter comments at the end of a line by preceding it with an exclamation mark (!). The following example illustrates the stimulus file format: STEP RA0 RA1 ! These are I/O pin names 8 1 0 16 0 1 ! followed by values 24 1 0 Other notes on the format of stimulus file: ù The number of spaces separating columns is irrelevant. ù The step count must be in decimal. Examples PICSIM Command Result % ST SAMPLE.STI PICSIM reads the specified stimulus file. Upon execution, it will retrieve input as designated in this file. Defaults The default injection point is "step". The default file extension is `.STI'. Related Commands IP ****************************************** TA - PRINT TRACE INSTRUCTIONS ****************************************** Syntax TA [address1, address2] Description This command sets the trace to print only those instructions located between address1 and address2. If you don't specify address1 and address2, PICSIM uses the full memory. Examples PICSIM Command Result % TA main, call_m Upon the invocation of the TC command, PICSIM will print/display only those instructions between main and mpy_S. Defaults Address range defaults to all of memory. Related Commands TC, TF, TR ****************************************** TC - TRACE INSTRUCTIONS ****************************************** Syntax TC #instructions Description This command traces the next #instructions instructions, displaying the instructions if they are valid. If you don't supply the #instructions, the trace continues indefinitely until encountering a breakpoint or until you press any key. Examples PICSIM Command Result % TC 3 Trace the next three instructions Defaults None. Related Commands TA, TF, TR ****************************************** TF - OPEN TRACE OUTPUT FILE/PRINT TRACE ****************************************** Syntax TF [filename |Prn] Description This command opens or closes a file for writing the trace, or prints the trace. If you enter PRN as an argument, PICSIM prints the trace to the default printer. If you supply filename, PICSIM opens that file, if you don't, PICSIM closes any currently opened output trace file. You must use the TF command BEFORE starting the trace: Examples PICSIM Command Result % TF Close the output trace file. % TF PRN Print the trace to the default printer. % TF SAMPLE.TRC Open SAMPLE.TRC and write the trace to it. Defaults None. Related Commands TA, TC, TR ****************************************** TR - TRACE REGISTER ****************************************** Syntax TR register [, min_value, max_value] Description This command sets the file register trace. If you don't supply any parameters, PICSIM traces any file register. If you specify register, it traces that register. If you also specify min_value and max_value, it performs the trace only if the value of the specified register lies between min_value and max_value. Examples PICSIM Command Result % TR Traces all registers % TR W Traces the W register % TR W 2 7 Traces the W register when its value falls between 2 and 7 (in the current radix) Defaults None. Related Commands TA, TC, TF ****************************************** TY - CHANGE VIEW SCREEN ****************************************** Syntax TY data_area,{X|O|D|B},#digits Description This command changes the formatting of existing view screen elements. Data_area names the pin or register. If it isn't in the view screen, PICSIM gives a warning. The radix can be hexadecimal, octal, decimal or binary, designated by X, O, D or B, respectively. #digits is the number of spaces to for this variable on the view screen. Examples PICSIM Command Result % TY RTCC,B,1 RTCC I/O pin displays in binary, using one digit. Defaults None. Related Commands AD, NV, V. ****************************************** V - VIEW SCREEN ****************************************** Syntax V signal [,radix [,digits]] Description This command creates a new view screen that displays the named signal or register. Optionally, you may specify a radix different from the default and/or a number of digits. V sets up the view screen. This means that the View command defines the variables (and respective formats) to constantly display on the screen. Once the view screen is set, it remains active until either an NV command or a V command sets up a new view screen. The format of this command is relatively simple. Register or signal s displays in radix mode r with n digits. The radix can be B (binary), O (octal), X (hexadecimal) or D (decimal). Examples PICSIM Command Result % V F3,b,8 A view screen element is created with the following format: F3: 00000000 % V RB0 A view screen element is created with the following format: RB0: 00 Defaults The radix ordinarily defaults to hexadecimal, but you can change this default with the SR command. Digits defaults according to the table below: Table 5.4 Radix Default Widths Radix Digits X 2 B 8 O 3 D 2 Related Commands AD, DV, NV, TY. ****************************************** W - DISPLAY/MODIFY THE WORK REGISTER ****************************************** Syntax W Description This command displays and/or modifies the contents of W register. Examples PICSIM Command Result % W W:44:00 The value of W is 44 as the following message shows. W:44: Change the value by entering a different value after the `:' prompt. The W register now has a value of 0 Defaults None. Related Commands None. ****************************************** ZM - ZERO THE PROGRAM MEMORY ****************************************** Syntax ZM address1, address2 Description This command zeros the program memory from address1 to address2. address1 must less than address2 and both must be valid program memory addresses. Examples PICSIM Command Result % ZM 0, 1F Program memory from 0 to 1F is zeroed. Defaults None. Related Commands None. ****************************************** ZP - ZERO THE PATCH TABLE ****************************************** Syntax ZP Description This command clears the patch table. Clears the patch table and resets it to no patches made. Any changes made to the object code are unaffected. Thus, the object code cannot be restored to the original. Examples PICSIM Command Result % ZP Patch table cleared. Defaults None. Related Commands O, RA, RP. ****************************************** ZR - ZERO THE REGISTERS ****************************************** Syntax ZR Description This command sets all of the file registers to zero. Care should be taken with this instruction since it will zero the lower 8 bits of F2 (PC). An RS command should follow the ZR command to ensure the PC is set the expected reset value. Examples PICSIM Command Result % ZR All registers are zeroed. Defaults None. Related Commands DR, RS, SE. ****************************************** ZT - ZERO THE ELAPSED TIME COUNTER ****************************************** Syntax ZT Description This command zeros the elapsed time counter. Examples PICSIM Command Result % ZT The elapsed time counter resets to zero. Defaults None. Related Commands RE, RS. ****************************************** ******************************************