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>µbe;</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 µbe; 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; ⪚ the name of a PIC16F84 is "P16F84".
0022
0023 <example><title>Simple complete µbe; 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>µbe; 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, µbe; 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; ⪚ 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>µbe;</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, µbe; 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 < y</para></listitem>
0393 <listitem><para><emphasis>Is greater than or equal to:</emphasis> x >= y</para></listitem>
0394 <listitem><para><emphasis>Is less than or equal to:</emphasis> x <= 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 <pin name></emphasis>
0418 - Occurs when the state of the specified pin changes. Pin name is in the usual syntax of PORTX.n, ⪚ <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>