Warning, /sdk/ktechlab/doc/en/microbe.docbook is written in an unsupported language. File is not indexed.

0001 <!-- kate: tab-width 2; indent-mode xml; -->
0002 <chapter id="microbe">
0003 <title>&microbe;</title>
0004 <sect1>
0005         <title>Introduction and General Syntax</title>
0006         <para>
0007                 <application>Microbe</application> compiles programs written in the custom language for PICs, as a companion program to &ktechlab;. The syntax has been designed to suit a &flowcode; program.
0008                 
0009                 The syntax for running <command>microbe</command> from the command line is:
0010                 
0011                 <programlisting>microbe [options] [input.microbe] [output.asm]</programlisting>
0012                 
0013                 where options are:
0014         </para>
0015                 <itemizedlist>
0016                         <listitem><para><function>--show-source</function> - Puts each line of &microbe; source code as a comment in the assembly output before the assembly instructions themselves for that line.</para></listitem>
0017                         <listitem><para><function>--no-optimize</function> - Prevent optimization of the instructions generated from the source. Optimization is usually safe, and so this option is mainly used for debugging.</para></listitem>
0018                 </itemizedlist>
0019                 
0020         <para>
0021                 The .microbe input file must identify the target PIC by inserting the PIC name at the top of the .microbe file; &eg; the name of a PIC16F84 is "P16F84".
0022                 
0023                 <example><title>Simple complete &microbe; program</title>
0024                         <programlisting role="correct">
0025 P16F84
0026 
0027 a = 0
0028 repeat
0029 {
0030         PORTA = a
0031         a = a + 1
0032 }
0033 until a == 5
0034 
0035 end</programlisting>
0036                         </example>
0037                 </para>
0038 
0039         <sect2 id="namingconventions">
0040                 <title>Naming conventions</title>
0041                 <para>
0042                         The following rules apply to variable names and labels:
0043                         <itemizedlist>
0044                                 <listitem><para>They can only contain alphanumerical characters [a..z][A..Z][0..9] and the underscore "_".</para></listitem>
0045                                 <listitem><para>They are case-sensitive.</para></listitem>
0046                                 <listitem><para>They cannot start with a number.</para></listitem>
0047                                 <listitem><para>They should not start with <quote>__</quote> (double underscore), as this is reserved for use by the compiler.</para></listitem>
0048                         </itemizedlist>
0049                 </para>
0050         </sect2>
0051 
0052         <sect2 id="bracingconventions">
0053                 <title>Bracing conventions</title>
0054                 <para>
0055                         Curly braces, {}, indicate the start and end of a code block.
0056                         
0057                         They can appear anywhere before the start and after the end of the code block.
0058                         
0059                         Examples of acceptable code blocks:
0060         <programlisting role="correct">
0061 statement1 {
0062         some code
0063 }</programlisting>
0064                 <programlisting role="correct">
0065 statement2 {
0066         other code }</programlisting>
0067                 
0068                 <programlisting role="correct">
0069 statement3
0070 {
0071         other code
0072 }</programlisting>
0073                 
0074                 <programlisting role="correct">
0075 statement5 {
0076         code block
0077 } statement6</programlisting>
0078                         </para>
0079                 </sect2>
0080                 <sect2 id="commenting">
0081                         <title>Commenting</title>
0082                         <para>
0083                                 Commenting is similar to C. // comments out the rest of the line. /* and */ denote a multiline comment.
0084                                 <programlisting role="correct">
0085 // This is a comment
0086 x = 2 
0087 /* As is this
0088 multiline comment */</programlisting>
0089                 </para>
0090         </sect2>
0091 
0092         <sect2 id="structure">
0093                 <title>Program Structure</title>
0094                 <para>
0095                                 The PIC id must be inserted at the top of the program. The end of the main program is denoted with <quote>end</quote>. Subroutines must placed after <quote>end</quote>.
0096                 </para>
0097         </sect2>
0098 
0099         <sect2 id="subroutines">
0100                 <title>Subroutines</title>
0101                 <para>
0102                         A subroutine can be called from anywhere in the code. Syntax:
0103                 </para>
0104                 <programlisting role="correct">
0105 sub SubName
0106 {
0107         // Code...
0108 }</programlisting>
0109 <para>The subroutine is called with <quote>call <replaceable>SubName</replaceable></quote>.</para>
0110         </sect2>
0111 </sect1>
0112 
0113 <sect1 id="languagereference">
0114         <title>&microbe; language reference</title>
0115         <sect2 id="if">
0116                 <title>if</title>
0117                 <para>Conditional branching.
0118                         
0119                         Syntax:
0120                         <programlisting role="correct">if [expression] then [statement]</programlisting>
0121                         or
0122                         <programlisting role="correct">
0123 if [expression] then
0124 {
0125         [statement block]
0126 }</programlisting>
0127                 
0128                         Similarly for else:
0129                         <programlisting role="correct">else [statement]</programlisting>
0130                         or
0131                         <programlisting role="correct">
0132 else
0133 {
0134         [statement block]
0135 }</programlisting>
0136                         </para>
0137                         
0138                         <example><title>if</title>
0139                         <programlisting role="correct">
0140 if porta.0 is high then
0141 {
0142         delay 200
0143 }
0144 else
0145 {
0146         delay 300
0147 }</programlisting>
0148                 </example>
0149         </sect2>
0150         
0151         <sect2 id="alias">
0152                 <title>alias</title>
0153                 <para>Aliases one string to another. Syntax:
0154                         <programlisting role="correct">alias [from] [to]</programlisting>
0155                 </para>
0156         </sect2>
0157         
0158         <sect2 id="repeat">
0159                 <title>repeat</title>
0160                 <para>Executes the statement block repeatedly until expression evaluates to true.
0161                         
0162                         The evaluation of the expression is performed after the statement block, so the statement block will always be executed at least once. Syntax:
0163         <programlisting role="correct">
0164 repeat
0165 {
0166         [statement block]
0167 }
0168 until [expression]</programlisting>
0169         </para>
0170 </sect2>
0171 
0172 <sect2 id="while">
0173 <title>while</title>
0174         <para>
0175         Similar to repeat, this repeatedly executes the statement block. However, the expression is evaluated before execution, not after. So if the expression evaluates to false on the first pass, then the statement block will not get executed.
0176         
0177         Syntax:
0178         <programlisting role="correct">
0179 while [expression]
0180 {
0181         [statement block]
0182 }</programlisting>
0183         </para>
0184 </sect2>
0185 
0186 
0187 <sect2 id="goto">
0188         <title>goto</title>
0189         <para>
0190                 This causes execution of the code to continue at the next statement after the label specified.
0191                 
0192                 Goto syntax:
0193                 <programlisting role="correct"><function>goto</function> [labelname]</programlisting>
0194                 
0195                 Label syntax:
0196                 <programlisting role="correct"><function>labelname:</function></programlisting>
0197                 
0198                 It is often considered good programming practice to avoid the use of goto. Use of control statements and subroutines will result in a much more readable program.
0199         </para>
0200         
0201         <example><title>goto</title>
0202         <programlisting role="correct">
0203 goto MyLabel
0204 
0205 ...
0206 
0207 [MyLabel]:
0208 // Code will continue at this point</programlisting>
0209                 </example>
0210         </sect2>
0211         
0212         <sect2 id="call">
0213                 <title>call</title>
0214                 <para>
0215                         Calls a subroutine.
0216                         
0217                         Syntax:
0218                         <programlisting role="correct"><function>call</function> [SubName]</programlisting>
0219                         where <replaceable>SubName</replaceable> is the name of the subroutine to be called.
0220                 </para>
0221         </sect2>
0222         
0223         <sect2 id="delay">
0224         <title>delay</title>
0225                 <para>
0226                 This causes the code execution to stop for the given period of time. The interval is in milliseconds.
0227                 
0228                 Syntax:
0229                 <programlisting role="correct"><function>delay</function> [interval]</programlisting>
0230                 
0231                 <note><para>At present, &microbe; assumes that the PIC is operating at a frequency of 4MHz - &ie; each instruction takes 1 microsecond to execute. If this is not the case, the interval must be adjusted proportionately.</para></note>
0232                 </para>
0233         </sect2>
0234         
0235         <sect2 id="sevenseg">
0236                 <title>sevenseg</title>
0237                 <para>This is used to define the pin mapping for a (common cathode) seven segment display connected to the PIC. Syntax:
0238                         <programlisting role="correct"><function>sevenseg</function> [name] [a] [b] [c] [d] [e] [f] [g]</programlisting>
0239                         
0240                         where [a]...[g] are the PIC pins to which the respective segments of the seven segment display are attached. The pins can be written either as PORTX.N or RXN.
0241                 </para>
0242                 
0243                 <para>To display a number on the seven segment, the pin mapping is treated as a write only variable.
0244                         <example>
0245                                 <title>Defining and outputting to a seven segment</title>
0246                                 <programlisting role="correct">
0247 sevenseg seg1 RB0 RB1 RB2 RB3 RB4 RB5 RB6
0248 seg1 = x + 2</programlisting>
0249                                 </example>
0250                 </para>
0251         </sect2>
0252         
0253         <sect2 id="keypad">
0254                 <title>keypad</title>
0255                 <para>This is used to define the pin mapping for a keypad connected to the PIC. Syntax:
0256                         <programlisting role="correct"><function>keypad</function> [name] [row 1] ... [row 4] [column 1] ... [column n]</programlisting>
0257                         
0258                         where [row 1] ... [row 4] and [column 1] ... [column n] are the PIC pins to which the respective rows and columns of the keypad are attached (at the moment, the number of rows is not changeable). See <xref linkend="sevenseg"/> (above) for more information on pin mappings.
0259                 </para>
0260                 
0261                 <para>The columns of the keypad should be pulled down via 100k resistors to ground. The row pins must be configured as outputs and the column pins as inputs. Once the keypad has been defined, it is treated as a read only variable.
0262                         <example>
0263                                 <title>Defining and reading from a keypad</title>
0264                                         <programlisting role="correct">
0265 keypad keypad1 RB0 RB1 RB2 RB3 RB4 RB5 RB6
0266 x = keypad1</programlisting>
0267                         </example>
0268                 </para>
0269                         
0270                 <para>
0271                         By default, the values returned for a keypad are:
0272                         <itemizedlist>
0273                                 <listitem><para>The value of the number if it is a numeric key (1 to 3 along top row; hexadecimal A to D down the fourth column and continuing for each extra column).</para></listitem>
0274                                 <listitem><para>253 for the key in row 4, column 1.</para></listitem>
0275                                 <listitem><para>254 for the key in row 4, column 3.</para></listitem>
0276                         </itemizedlist>
0277                         These values can be redefined by using the alias command, where the name of the key in row x, column y (rows and columns starting at 1), is Keypad_x_y. For example, to give the star key on a 4x3 keypad the value zero, the following alias would be used:
0278                         <example>
0279                                 <title>Aliasing a keypad key to a value</title>
0280                                 <programlisting role="correct">alias Keypad_4_1 0</programlisting>
0281                         </example>
0282                 </para>
0283         </sect2>
0284 </sect1>
0285 
0286 <sect1 id="picio">
0287 <title>PIC I/O</title>
0288         
0289         <sect2 id="tristate">
0290         <title>Port Direction</title>
0291                 <para>
0292                 The port direction is set by assigning a value to TRIS*, where * is the port letter. For example:
0293                 </para>
0294                 <example><title>Setting port directions</title>
0295                 <programlisting role="correct">TRISB = b'01111001'</programlisting>
0296                 </example>
0297                 <para>
0298                 The above sets pins RB1, RB2 and RB7 on PORTB as outputs, and the other pins on PORTB as inputs. In this example, b'01111001' is a binary representation of the output type. The 1 on the right represents an output on RB0, and the 0 on the left represents an input on RB7.
0299                 </para>
0300         </sect2>
0301         
0302         <sect2 id="ports">
0303         <title>Port I/O</title>
0304                 <para>
0305                 The port can be treated as a variable. For example:
0306                 </para>
0307                 
0308                 <example><title>Writing to a port</title>
0309                 <programlisting role="correct">x = PORTA</programlisting>
0310                 </example>
0311                 
0312                 <para>
0313                 The above assigns the value of PORTA to the variable x.
0314                 </para>
0315         </sect2>
0316         
0317         <sect2 id="pins">
0318         <title>Pin I/O</title>
0319                 <para>
0320                 Each pin on a port is obtained by prefixing the pin number by the port name; &eg; Pin 2 (starting from Pin 0) on PORTA is known as
0321                 <emphasis>PORTA.0</emphasis>.
0322                 
0323                 The syntax to set a pin state is:
0324                 <programlisting role="correct">PORTX.N = <emphasis>STATE</emphasis></programlisting>
0325                 where <emphasis>STATE</emphasis> can be <emphasis>high</emphasis> or <emphasis>low</emphasis>.
0326                 
0327                 The syntax to test a pin state is:
0328                 <programlisting role="correct"><function>if</function> PORTX.N is <emphasis>STATE</emphasis> <function>then</function></programlisting>
0329                 
0330                 Combining these examples, we have:
0331                 </para>
0332                 <example><title>Setting and testing pin state</title>
0333                 <programlisting role="correct">
0334 TRISA = 0
0335 TRISB = 255
0336 <function>if</function> PORTA.3 is <function>high</function> <function>then</function>
0337 {
0338         PORTB.5 = <function>low</function>
0339 }
0340 <function>else</function>
0341 {
0342         PORTB = PORTA + 15
0343 }</programlisting>
0344                 </example>
0345         </sect2>
0346 </sect1>
0347         
0348 <sect1 id="variables">
0349 <title>Variables</title>
0350         <para>
0351         All variables are 8-bit unsigned integers, giving a range from 0 to 255.
0352         
0353         <application>&microbe;</application> supports the typical unary operations (acting on one variable) and binary operations (acting on two variables) that are supported by the PIC. In addition, &microbe; also supports division and multiplication.
0354         </para>
0355         <sect2 id="unary">
0356         <title>Unary Operations</title>
0357                 <para>
0358                 <itemizedlist>
0359                 <listitem><para><emphasis>rotateleft x</emphasis> - Rotates the variable x left through carry.</para></listitem>
0360                 <listitem><para><emphasis>rotateright x</emphasis> - Rotates the variable x right through carry.</para></listitem>
0361                 <listitem><para><emphasis>increment x</emphasis> - Increments the variable x. If x has a value of 255, then x wraps round to 0.</para></listitem>
0362                 <listitem><para><emphasis>decrement x</emphasis> - Decrements the variable x. If x has a value of 0, then x wraps round to 255.</para></listitem>
0363                 </itemizedlist>
0364                 </para>
0365         </sect2>
0366         
0367         <sect2 id="arithmetic">
0368         <title>Arithmetic</title>
0369                 <para>
0370                 Supported operations:
0371                 <itemizedlist>
0372                 <listitem><para><emphasis>Addition:</emphasis> x + y</para></listitem>
0373                 <listitem><para><emphasis>Subtraction:</emphasis> x - y</para></listitem>
0374                 <listitem><para><emphasis>Multiplication:</emphasis> x * y</para></listitem>
0375                 <listitem><para><emphasis>Division:</emphasis> x / y</para></listitem>
0376                 <listitem><para><emphasis>Binary XOR:</emphasis> x XOR y</para></listitem>
0377                 <listitem><para><emphasis>Binary AND:</emphasis> x AND y</para></listitem>
0378                 <listitem><para><emphasis>Binary OR:</emphasis> x OR y</para></listitem>
0379                 </itemizedlist>
0380                 </para>
0381         </sect2>
0382         
0383         <sect2 id="comparison">
0384         <title>Comparison</title>
0385         <para>
0386         Supported operations:
0387         </para>
0388         <itemizedlist>
0389         <listitem><para><emphasis>Equals:</emphasis> x == y</para></listitem>
0390         <listitem><para><emphasis>Does not equal:</emphasis> x != y</para></listitem>
0391         <listitem><para><emphasis>Is greater than:</emphasis> x > y</para></listitem>
0392         <listitem><para><emphasis>Is less than:</emphasis> x &lt; y</para></listitem>
0393         <listitem><para><emphasis>Is greater than or equal to:</emphasis> x &gt;= y</para></listitem>
0394         <listitem><para><emphasis>Is less than or equal to:</emphasis> x &lt;= y</para></listitem>
0395         </itemizedlist>
0396         
0397         <para>
0398         For example:
0399         </para>
0400         <example><title>Comparison</title>
0401         <programlisting role="correct">
0402 <function>if</function> PORTA >= 5 <function>then</function>
0403 {
0404         ...
0405 }</programlisting>
0406         </example>
0407         </sect2>
0408 </sect1>
0409 
0410 <!--
0411 <sect1 id="interrupts">
0412 <title>Interrupts</title>
0413         <para>
0414         There are several types of events, and some of these take an optional parameter making
0415         the condition under which the routine is called more specific.
0416         <itemizedlist>
0417         <listitem><para><emphasis>change &lt;pin name&gt;</emphasis>
0418                  - Occurs when the state of the specified pin changes. Pin name is in the usual syntax of PORTX.n, &eg; <programlisting>interrupt change PORTB.4</programlisting></para></listitem>
0419         <listitem><para><emphasis>timer</emphasis> - ///TODO</para></listitem>
0420         <listitem><para><emphasis>external</emphasis> - ///TODO</para></listitem>
0421         </itemizedlist>
0422         </para>
0423 </sect1>
0424 -->
0425 </chapter>