diff options
Diffstat (limited to 'doc/handbook/mcu8051ide.en.tex')
| -rw-r--r-- | doc/handbook/mcu8051ide.en.tex | 40 |
1 files changed, 24 insertions, 16 deletions
diff --git a/doc/handbook/mcu8051ide.en.tex b/doc/handbook/mcu8051ide.en.tex index 0139b7b..5f4d5a0 100644 --- a/doc/handbook/mcu8051ide.en.tex +++ b/doc/handbook/mcu8051ide.en.tex @@ -1,8 +1,8 @@ \documentclass[a4paper,twoside,12pt]{book} \usepackage[utf8]{inputenc} -\title{MCU 8051 IDE handbook draft} -\author{Martin Ošmera <martin.osmera@gmail.com>} +\title{MCU 8051 IDE handbook} +\author{Martin Ošmera <martin.osmera@moravia-microsystems.com>} \newcommand{\mysubject}{MCU~8051~IDE handbook} \newcommand{\mykeywords}{8051, IDE, Linux} @@ -110,7 +110,8 @@ \addcontentsline{toc}{chapter}{Preface} \section*{Goals of the project} \addcontentsline{toc}{section}{Goals of the project} - MCU~8051~IDE is an integrated development environment for microcontrollers based on MCS-51 intended for Assembly language and C language. This IDE is currently available on GNU/Linux and Microsoft\textregistered\~Windows\textregistered\ (since version 1.3.6). This program was originally intended for education purposes, but now the area of potential usage is surely significantly wider. This program was created to fill a gap in the open source software of this kind. User interface, source codes, documentation, web pages, etc., are written in English in order to make this software available to as many user as possible, but there is support for internationalization using i18n since version 1.3.10. This documentation is written in \LaTeX. It is very important to note that this software was not developed for any company, person or something similar and it is completely noncommercial, open source software distributed under \href{http://gnu.cz/article/30/pdf/gpl-cz.pdf}{GNU GPLv2} license intended for a group of people with common interest, in this case 8051. + MCU~8051~IDE is an integrated development environment for microcontrollers based on MCS-51 intended for Assembly language and C language. This IDE is currently available on GNU/Linux and Microsoft\textregistered\~Windows\textregistered\ (since version 1.3.6). This program was originally intended for education purposes, but now the area of potential usage is surely significantly wider. This program was created to fill a gap in the open source software of this kind. User interface, source codes, documentation, web pages, etc., are written in English in order to make this software available to as many user as possible, but there is support for internationalization using i18n since version 1.3.10. This documentation is written in \LaTeX. It is very important to note that this software was not developed for any company, person or something similar and it is completely noncommercial, open source software distributed under \href{http://gnu.cz/article/30/pdf/gpl-cz.pdf}{GNU GPLv2} license intended for a group of +people with common interest, in this case 8051. \subsection*{MCU 8051 IDE should offer:} \begin{dingautolist}{172} @@ -196,7 +197,8 @@ \section{Main components of MCU 8051 IDE} \paragraph{Editor} The code editor is featured with syntax highlighting and validation, auto-completion and spell checking for comments \footnote{Spell checking for comments is available only if you have installed the Hunspell program. This feature is currently not available on MS\textregistered Windows\textregistered OS.}, as well as a command line that speeds up the access to various editor options. It also provides a panel showing line numbers, bookmarks, breakpoints and warnings from syntax validator. Editor is capable to export the source code within it as XHTML and \LaTeX\ and contains a number of useful tools like automatic indentation, searching and replacement of expressions, copy to clipboard, paste from clipboard, among others. - \paragraph{Assembler} The assembler is one of the integral parts of MCU 8051 IDE. It is a macro assembler with support for dozens of directives and capable of performing peephole optimizations. Support for peephole optimizations means that the assembler can attempt to optimize the resulting code for higher execution speed and lower size without tempering with its very functionality. It is important to note that automatic peephole optimization can sometimes be harmful and so it is disabled by default. A macro assembler is a software that allows the user to define a \textbf{macro instruction}, which consists of a sequence of basic instructions, and use it later instead of repeatedly copying and pasting the set of instructions over and over along the source code. Assembler behavior can be configured either globally, using the proper configuration dialog, or locally in source code, by means of assembler directives and control sequences (e.g. \texttt{\$TITLE('Some title to show in the code listing')}). The assembler is capable of generating four kinds of output code: + \paragraph{Assembler} The assembler is one of the integral parts of MCU 8051 IDE. It is a macro assembler with support for dozens of directives and capable of performing peephole optimizations. Support for peephole optimizations means that the assembler can attempt to optimize the resulting code for higher execution speed and lower size without tempering with its very functionality. It is important to note that automatic peephole optimization can sometimes be harmful and so it is disabled by default. A macro assembler is a software that allows the user to define a \textbf{macro instruction}, which consists of a sequence of basic instructions, and use it later instead of repeatedly copying and pasting the set of instructions over and over along the source code. Assembler behavior can be configured either globally, using the proper configuration dialog, or locally in source code, by means of assembler directives and control sequences (e.g. \texttt{\$TITLE('Some title to show in the code listing')}). The +assembler is capable of generating four kinds of output code: \begin{dinglist}{43} \setlength{\itemsep}{-3pt} \item Object code (machine code) as an hexadecimal file, with \fileextension{.hex} extension and in Intel\textregistered\ 8 HEX format; @@ -205,8 +207,10 @@ \item Code for integrated MCU simulator, in \fileextension{.adf} extension. \end{dinglist} - \paragraph{Simulator} The simulator is a software component intended for the simulation of the chosen microcontroller in a virtual environment. It allows user to monitor precisely what is happening in the MCU in an exact moment in time, as well as to modify its components, for instance by altering the value of a register, canceling an interrupt or forcing a subprogram to return. In that way it might be possible to ferret out certain flaws in the program being debugged, which would be hard or nearly impossible to find and/or fix in other ways. Even though it is better to have ICD (In-Circuit Debugger) or ICE (In-Circuit Emulator) at hand, MCU~8051~IDE in current version does not support neither of them % \textcolor{blue}{[MARTIN, ARE YOU PLANNING TO ADD SUPPORT ON NEXT VERSIONS? IF SO, IT IS GOOD TO MENTION THIS HERE.]}. :) Sorry Andre, the only think I plan regarding this project is to "retire", I was working on it during my studies on the school, now I've got another responsibilities to attend to, I am really sorry. - MCU simulator implemented in this IDE supports dozens of microcontrollers and most of them are treated in slightly different way allowing to take into account most of the nuances between the supported MCUs. User can adjust simulator behavior to fit his or her needs by modifying clock frequency, size of connected external code, data memory and others, or for instance by disabling or enabling certain warnings, which pops up when the simulated program do something ``strange'', like some kind of invalid access into memory or stack overflow or underflow. Besides that, it is possible for the user to modify all registers which the MCU deals with, including those which are not accessible by the running program, like the Program Counter. User have always an overview of all possible, pending and active interrupts and can temper with them at any time. The simulator also allows for altering code memory and all kinds of data memories. The program being simulated can be at any time "hibernated" into a file, preferably with \fileextension{.m5ihib} extension, and resumed later from this same file. Such a file contains the entire state of the simulator at the point in which the program was hibernated. + \paragraph{Simulator} The simulator is a software component intended for the simulation of the chosen microcontroller in a virtual environment. It allows user to monitor precisely what is happening in the MCU in an exact moment in time, as well as to modify its components, for instance by altering the value of a register, canceling an interrupt or forcing a subprogram to return. In that way it might be possible to ferret out certain flaws in the program being debugged, which would be hard or nearly impossible to find and/or fix in other ways. Even though it is better to have ICD (In-Circuit Debugger) or ICE (In-Circuit Emulator) at hand, MCU~8051~IDE in current version does not support neither of them % \textcolor{blue}{[MARTIN, ARE YOU PLANNING TO ADD SUPPORT ON NEXT VERSIONS? IF SO, IT IS GOOD TO MENTION THIS HERE.]}. :) Sorry Andre, the only think I plan regarding this project is to "retire", I was working on it during my studies on the school, now I've got another responsibilities to attend to, I am +really sorry. + MCU simulator implemented in this IDE supports dozens of microcontrollers and most of them are treated in slightly different way allowing to take into account most of the nuances between the supported MCUs. User can adjust simulator behavior to fit his or her needs by modifying clock frequency, size of connected external code, data memory and others, or for instance by disabling or enabling certain warnings, which pops up when the simulated program do something ``strange'', like some kind of invalid access into memory or stack overflow or underflow. Besides that, it is possible for the user to modify all registers which the MCU deals with, including those which are not accessible by the running program, like the Program Counter. User have always an overview of all possible, pending and active interrupts and can tamper with them at any time. The simulator also allows for altering code memory and all kinds of data memories. The program being simulated can be at any time "hibernated" into a file, preferably +with \fileextension{.m5ihib} extension, and resumed later from this same file. Such a file contains the entire state of the simulator at the point in which the program was hibernated. \paragraph{Project management} It is a functionality that allows the IDE to remember certain set of source code files along with a set of configuration parameters. Projects are stored in XML (eXtensible Markup Language) files with extension \fileextension{.mcu8051ide}. These files are human readable and their precise formatting is described in their inline DTD (Document Type Declaration). Their encoding is UTF-8 (Unicode Transformation) and as EOL (End Of Line) character they use LF (Line Feed). The reason for that is to make it possible for the user to implement his or her own tools for manipulating with them. @@ -220,7 +224,7 @@ \paragraph{Notepad} In this IDE, it is a simple rich text editor for writing user notes of whatever kind. Originally, it was intended for writing a list of things which remain to be done in your project. - \paragraph{Command Line Interface (CLI)} It is an useful tool that allows the use of some IDE functions without entering it's GUI. You can get list of available options by typing \texttt{mcu8051ide -h} or \texttt{mcu8051ide --help} to your terminal emulator. You can, for example, use just the assembler of the IDE or convert an Intel\textregistered{}~HEX~8 file to a raw binary file. + \paragraph{Command Line Interface (CLI)} It is a tool that allows the use of some IDE functions without entering it's GUI. You can get list of available options by typing \texttt{mcu8051ide -h} or \texttt{mcu8051ide --help} to your terminal emulator. You can, for example, use just the assembler of the IDE or convert an Intel\textregistered{}~HEX~8 file to a raw binary file. \section{What is MCS-51} \begin{wrapfigure}{r}{120pt} @@ -267,7 +271,7 @@ \end{wrapfigure} At first let me explain what the MCU~8051~IDE's project really is. It is a set of some files in some directory, let's call this directory the project directory. And this along with the file with extension \fileextension{.mcu8051ide} forms the project. The file with \fileextension{.mcu8051ide} extension defines what source code files belongs to the project and contains additional information about the project, like who is the project author or for what exact MCU is the project intended. - To create you project in you have to specify the project directory and the MCU type for which you will develop your code. This is done in project creation dialog. This dialog can be accessed from main menu ``\menuitem{Main Menu}'' $\rightarrow$ ``\menuitem{Project}'' $\rightarrow$ ``\includegraphics[height=8pt]{img/filenew.png} \menuitem{New}''. After this step you can specify some additional information about the project in project editing dialog. + To create you project you have to specify the project directory and the MCU type for which you will develop your code. This is done in project creation dialog. This dialog can be accessed from main menu ``\menuitem{Main Menu}'' $\rightarrow$ ``\menuitem{Project}'' $\rightarrow$ ``\includegraphics[height=8pt]{img/filenew.png} \menuitem{New}''. After this step you can specify some additional information about the project in project editing dialog. Once you have created a new project you can begin to develop you code from your chosen processor. When you want to save your code press Ctrl+S, Ctrl+N creates a new file and an existing file can be opened by Ctrl+O. Each opened file can be added or removed to/from your current project. Ctrl+B creates or deletes bookmark and Ctrl+Shift+B creates or deletes breakpoint. Project files, the files which are parts of the project, are opened each time you open the project. You can have more than one project opened at the time. @@ -306,7 +310,7 @@ \end{wrapfigure} Pop-up based auto-completion is function which should make it easier to use long names for labels, macros, variables, functions, constants, etc. This function is interconnected with syntax editor's analyzer used for syntax highlight and validation and for the table of symbols in the right panel. So it maintains an overview of all symbols defined in your source code file and then when you write just a few characters which a symbol starts with, this function will pop-up window offering you all defined symbols beginning with that letters. Note that this feature can be disabled in editor configuration dialog and note also that besides symbols it offers also list of assembly language instruction mnemonics and assembler directives. \subsection{Editor command line} - Editor is featured with a command line, which can be invoked by pressing F10 key by default. The command line appears below the editor above its status bar. From the command line you can perform variety of operations like conversions between various numerical bases, run simulator, insert current date and many more. In the command line it is sufficient to write just a few characters which the requested command starts with and which are sufficient to uniquely identify the command and press enter. You can see help for each command by running command \texttt{help list}. Command line is featured with its own color highlight, history and auto-completion. + Editor is featured with a command line, which can be invoked by pressing F10 key by default, and dismissed by pressing Esc. The command line appears below the editor above its status bar. From the command line you can perform variety of operations like conversions between various numerical bases, run simulator, insert current date and many more. In the command line it is sufficient to write just a few characters which the requested command starts with and which are sufficient to uniquely identify the command and press enter. You can see help for each command by running command \texttt{help list}. Command line is featured with its own color highlight, history and auto-completion. { \mysmallfont{} \begin{longtable}{l|ll} @@ -575,7 +579,7 @@ \clearpage \subsection{ASCII chart} - Colorful interactive ASCII chart, it may proof handy especially when you are dealing with serial communication and this sort of things. + Colorful interactive ASCII chart, it may prove handy especially when you are dealing with serial communication and this sort of things. \subsection{8051 Instruction Table} Colorful interactive 8051 instruction table, very much alike the ASCII chart. But instead of ASCII code you can find there the complete table of 8051 instruction mnemonics, OP codes and related things. @@ -662,7 +666,7 @@ \end{itemize} \subsection{Normalization of source code indentation} - Uniformly indented code is always more aesthetically pleasing and more readable. When you don't have the luxury of having such a code from the first hand, perhaps you will find this feature helpful. This function is available for assembly language and C language if program indent is installed on your system. User can access this function from the ``\menuitem{Main Menu}'' $\rightarrow$ ``\menuitem{Tools}'' $\rightarrow$ ``\menuitem{Auto indent}''. + Uniformly intended code is always more aesthetically pleasing and more readable. When you don't have the luxury of having such a code from the first hand, perhaps you will find this feature helpful. This function is available for assembly language and C language if program indent is installed on your system. User can access this function from the ``\menuitem{Main Menu}'' $\rightarrow$ ``\menuitem{Tools}'' $\rightarrow$ ``\menuitem{Auto indent}''. \noindent \begin{center} @@ -875,7 +879,8 @@ Symbol names for numbers, macros or addresses defined by user in the code using appropriate directive. Like with ``\texttt{equ}'' directive you can define a new symbol and assign a value to it right away. Symbols may consist of upper and lower case letter, digits and underscore character (``\_''), their length is not limited, they are case insensitive and they can be the same as language keywords. Be aware of that there cannot coexists two or more symbols in the same memory segment which differs only by letter casing, in other words symbols ``\texttt{abc}'' and ``\texttt{ABC}'' are completely the same thing. \section{Constants} - There are two types of constants numeric constants and character constants. Numeric constants consist of a sequence of digits allowed for the numeric base used and followed by the radix specifier. If the number begins with a letter, there must be the zero digit placed before the number. For example ``abh'' is not valid numeric constant, but ``0abh'' is. Character constants consist of sequence of one or more characters enclosed by quote character (\verb"'"). C escape sequences can be used in character constants. If you want to place quote character (\verb"'") into the constant, you can either place two quotes instead of one (``\verb"''''"'') or escape the quote, that means place backslash ``\\\\'' before it. There is significant difference between single character constant and multiple character one. Single character constant is regarded by assembler as 8 bin integer number and multiple character constant is a string, a sequence of characters. Since version 1.4.1 it is possible to use prefix ``0x'' (and ``0X'') as radix specifier for hexadecimal numbers, so ``0xaf'' is the same as ``0afh'', etc. + There are two types of constants numeric constants and character constants. Numeric constants consist of a sequence of digits allowed for the numeric base used and followed by the radix specifier. If the number begins with a letter, there must be the zero digit placed before the number. For example ``abh'' is not valid numeric constant, but ``0abh'' is. Character constants consist of sequence of one or more characters enclosed by quote character (\verb"'"). C escape sequences can be used in character constants. If you want to place quote character (\verb"'") into the constant, you can either place two quotes instead of one (``\verb"''''"'') or escape the quote, that means place backslash ``\\\\'' before it. There is significant difference between single character constant and multiple character one. Single character constant is regarded by assembler as 8 bin integer number and multiple character constant is a string, a sequence of characters. Since version 1.4.1 it is possible to use prefix ``0x'' (and +``0X'') as radix specifier for hexadecimal numbers, so ``0xaf'' is the same as ``0afh'', etc. \begin{table}[h!] \mysmallfont{} @@ -2082,7 +2087,8 @@ As you can see from the example above, the code generated by disassembler is the same as the original code. But of course original symbol names have vanished as well as comments, indentation and other tiny details which cannot be determined from the object code. This is caused by the simple fact that the object code contains only the machine code. It contains no information regarding how exactly the original code looked like. Just instructions with their operands and data directly written to the code memory by ``DB'' and ``DW'' directives. And here we are getting to the real problem which emerges every time when you try to disassemble ``not exactly a simple'' code. - 8051 instructions comprises of 1, 2 or 3 bytes, the first byte determinates what instruction are we dealing with and so what is its length in bytes. But if the original code contained directives ``DB'' or ``DW'' then the disassembler ``thinks'' that these values are instructions too. If the disassembler consider a arbitrary value given by ``DB'' or ``DW'' instruction to be an instruction, it determinates its length according to its OP code (the 1st argument to the directive). And so it takes 0, 1 or 2 bytes next and interprets them as operands to that instruction. Then when it encounters a real instruction OP code it might think of it as another operand to something and so misinterpret it. Then you might end up with a code that is completely different from the original code and makes no sense at all to human. But if you reassemble such a ``non sense'' code with disabled peep hole optimization you must get the original object code back, and its functionality must not be changed. Even if the code seems to be absolutely non sense. In that case I strongly recommend to use another disassembler than is the built-in one. Consider for example D52 \url{http://www.8052.com/users/disasm/}. The built-in diassembler is provided just for ``completeness'', but its suitability for a real reverse engineering is highly questionable. + 8051 instructions comprises of 1, 2 or 3 bytes, the first byte determinates what instruction are we dealing with and so what is its length in bytes. But if the original code contained directives ``DB'' or ``DW'' then the disassembler ``thinks'' that these values are instructions too. If the disassembler consider a arbitrary value given by ``DB'' or ``DW'' instruction to be an instruction, it determinates its length according to its OP code (the 1st argument to the directive). And so it takes 0, 1 or 2 bytes next and interprets them as operands to that instruction. Then when it encounters a real instruction OP code it might think of it as another operand to something and so misinterpret it. Then you might end up with a code that is completely different from the original code and makes no sense at all to human. But if you reassemble such a ``non sense'' code with disabled peep hole optimization you must get the original object code back, and its functionality must not be changed. Even if the code seems to be +absolutely non sense. In that case I strongly recommend to use another disassembler than is the built-in one. Consider for example D52 \url{http://www.8052.com/users/disasm/}. The built-in diassembler is provided just for ``completeness'', but its suitability for a real reverse engineering is highly questionable. \bigskip \noindent @@ -2261,7 +2267,7 @@ \enlargethispage{6\baselineskip} \subsection{LCD display controlled by HD44780} - This tool simulates a HD44780 character LCD of any size up to 2 rows and 40 columns. There are 11 I/O lines serving as interface for the MCU, ``E'', ``RS'', ``R/W'' and ``D0''..``D7''. User can view end modify content of the display data RAM (DDRAM), the character generator RAM (CGRAM) and certain HD44780 registers: instruction register (IR), data register (DR), address counter (AC) and display shift, these registers are shown in hexadecimal representation. + This tool simulates a HD44780 character LCD of any size up to 2 rows and 40 columns. There are 11 I/O lines serving as interface for the MCU, ``E'', ``RS'', ``R/W'' and ``D0''..``D7''. User can view and modify content of the display data RAM (DDRAM), the character generator RAM (CGRAM) and certain HD44780 registers: instruction register (IR), data register (DR), address counter (AC) and display shift, these registers are shown in hexadecimal representation. User can also view content of character generator ROM (CGROM) and set font to use. All of the driver commands are fully supported and all important events occurring in the simulated driver (HD44780) are recorded in the simulator log. User can also see and modify certain HD44780 configuration flags like ``B'', ``S'', ``D'' and so on. And the window is collapsible. \begin{figure}[h!] \begin{minipage}[b]{.5\textwidth} @@ -2305,7 +2311,8 @@ \includegraphics[width=110pt]{img/ssp89s_sceenshot.png} \caption{An example of HW control plug-in} \end{wrapfigure} - It is not surprising that IDE for micro-controllers should be capable of inter-operation with certain hardware tools. MCU~8051~IDE has tool named HW plug-ins manager which is responsible for loading and managing plug-ins written in order to to ``integrate'' exiting hardware tools into this IDE. With this feature every author of a 8051 programmer, ICD, ICE etc. who knows Tcl/Tk language has the opportunity to make his or her own tool working in direct cooperation with the IDE. These plug-ins have to be written at least partially in the TCL language and use the Tk library along with API of MCU~8051~IDE. But that doesn't mean that they should be written entirely in Tcl/Tk. On the contrary I would encourage usage of another languages for example SSP89S, also a part of MCU~8051~IDE project, is written almost completely in C++/Qt4, but only a ``small'' piece of the software is written in Tcl/Tk. Tcl/Tk can easily inter-operate with C and C++, also it is possible to run arbitrary separate process from inside of Tcl/Tk program and control it vie for example TCP sockets or its stdin/stdout or something else. + It is not surprising that IDE for micro-controllers should be capable of inter-operation with certain hardware tools. MCU~8051~IDE has tool named HW plug-ins manager which is responsible for loading and managing plug-ins written in order to to ``integrate'' exiting hardware tools into this IDE. With this feature every author of a 8051 programmer, ICD, ICE etc. who knows Tcl/Tk language has the opportunity to make his or her own tool working in direct cooperation with the IDE. These plug-ins have to be written at least partially in the TCL language and use the Tk library along with API of MCU~8051~IDE. But that doesn't mean that they should be written entirely in Tcl/Tk. On the contrary I would encourage usage of another languages for example SSP89S, also a part of MCU~8051~IDE project, is written almost completely in C++/Qt4, but only a ``small'' piece of the software is written in Tcl/Tk. Tcl/Tk can easily inter-operate with C and C++, also it is possible to run arbitrary separate process from inside of +Tcl/Tk program and control it vie for example TCP sockets or its stdin/stdout or something else. \section{How to write your own plug-in} At first take these steps: @@ -2557,7 +2564,8 @@ } \chapter{Translating the IDE into different languages} - The IDE can be translated to almost any language. The translation can be accomplished by creating of a translation definition file. Such a file must follow certain strict rules in order to work properly. Translation files are normally located in directory ``/usr/share/mcu8051ide/translations'', on Microsoft\textregistered Windows\textregistered the directory is ``<YourInstallationDirectory>\verb'\'translations''. There you can find file ``template.txt'' which is template of MCU 8051 IDE translation file. Along with it there is also file ``languages.txt'' which defines names of languages to which the IDE was already translated. These names are written in these languages. Translation files look like this ``ru.msg'' (Russian translation) or ``cs.msg'' (Czech translation), these files need to be regularly updated. Note also that these files are quite big, each about 0.5MB and each contains about 4500 translated sentences. Further details regarding the translation are mentioned directly in the files related to translation, particularly in file ``template.txt''. Refer to them if you are interested in making your own translation of the IDE. This is an open-source project so any help is appreciated. + The IDE can be translated to almost any language. The translation can be accomplished by creating of a translation definition file. Such a file must follow certain strict rules in order to work properly. Translation files are normally located in directory ``/usr/share/mcu8051ide/translations'', on Microsoft\textregistered Windows\textregistered the directory is ``<YourInstallationDirectory>\verb'\'translations''. There you can find file ``template.txt'' which is template of MCU 8051 IDE translation file. Along with it there is also file ``languages.txt'' which defines names of languages to which the IDE was already translated. These names are written in these languages. Translation files look like this ``ru.msg'' (Russian translation) or ``cs.msg'' (Czech translation), these files need to be regularly updated. Note also that these files are quite big, each about 0.5MB and each contains about 4500 translated sentences. Further details regarding the translation are mentioned directly in the files related to +translation, particularly in file ``template.txt''. Refer to them if you are interested in making your own translation of the IDE. This is an open-source project so any help is appreciated. \bigskip \noindent |