Revision: 1176 Author: robhamerling Date: Sat Aug 8 02:29:47 2009 Log: Some sections or paragraphs moved to a more logical place. Changed alias declarations to 2.4l style with 'alias' keyword. Added a section about timer related registers and subfield naming convention.
http://code.google.com/p/jallib/source/detail?r=1176 Modified: /trunk/doc/html/devicefiles.html ======================================= --- /trunk/doc/html/devicefiles.html Wed Aug 5 12:47:32 2009 +++ /trunk/doc/html/devicefiles.html Sat Aug 8 02:29:47 2009 @@ -212,8 +212,8 @@ enable_digital_io() -- disable analog module(s) - var volatile bit led is pin_A1 -- declare alias for pin_A1 - var volatile bit led_direction is pin_A1_direction + alias led is pin_A1 -- declare alias for pin_A1 + alias led_direction is pin_A1_direction -- and for its direction led_direction = output -- make LED-pin output forever loop -- endless loop @@ -224,8 +224,7 @@ end loop </pre> - -<p>When loaded in a 16F886 with 20 MHz resonator or crystal an LED connected +When loaded in a 16F886 with 20 MHz resonator or crystal an LED connected (with series resistor!) to pin 3 (RA1) should blink twice a second. <h2>Naming conventions for Ports and Pins</h2> @@ -237,9 +236,10 @@ As a rule the device files use the names as used by the datasheets. However the device files have been generated from the MPLAB information files, not from the datasheets! -So it is possible that some names may not be conform the datasheet. -When you find such a deviation, please report to the Jallib team, -and most likely the next release will contain the corrected name. +So it is possible that some names may not be conform to the datasheet. +When you find such a deviation not mentioned in this document, please +report to the Jallib team, and most likely the next release will contain +the corrected name. <p>For all registers of the chip a name is declared and where appropriate also the individual bits or groups of bits are declared. @@ -247,15 +247,11 @@ <pre> var volatile bit INTCON_GIE at INTCON : 7 </pre> -<br>Some aliases are declared for easy migration or conversion of +Some aliases are declared for easy migration or conversion of existing JalV2 libraries and programs to the Jallib environment. <p>There are exceptions to the rules above. -For example the interrupt bits of Timer 0 are declared as TMR0IE and -TMR0IF for <b>all</b> devices, even though some datasheets use the names -T0IE and T0IF. -This is just an example, see below for more. -<br>The aim of this 'normalization' is: +<br>The aim of 'normalization' (using a consistent naming) is: <ol> <li>to be able to use all libraries for all types of PICmicros <li>to ease the migration of programs to other types of PICs. @@ -271,7 +267,7 @@ var volatile bit pin_A0 at PORTA : 0 var volatile bit pin_A0_direction at TRISA : 0 </pre> -<p>etc. (for all other existing pins and ports) +etc. (for all other existing pins and ports) <h3>GPIO and TRISIO (with the smaller chips)</h3> <p>Although the smaller PICs have no 'official' PORTA and TRISA registers, @@ -286,27 +282,11 @@ var volatile bit pin_A0 at GPIO : 0 var volatile bit pin_A0_direction at TRISIO : 0 </pre> -<p>etc. (for all other existing pins) - -<h3>Non-memory-mapped registers</h3> -<p>Some PICs, mainly in the baseline series, are missing some -addressable ('memory mapped') registers. -For example the 12-bit core PICs (10Fs, 12F5x, etc) have no memory -mapped TRISx registers, in stead these PICs have TRISx instructions to -set the direction of ports or pins. -This would make it impossible for function libraries and application -programs to use statements like: -<pre> - PORTA_direction = all_output -</pre> -<p>The device files contain pseudo variables which mimic the existence -of memory mapped registers, -which makes it possible to use statements like the one above. -<p>For example: even though a 16F59 has no addressable TRISC register, -you can still specify: -<pre> - pin_C5_direction = output -</pre> +etc. (for all other existing pins) +<p>Pins which can be input-only may have no corresponding _direction +variable, for example pin_E3 of the 18F4550. + + <h3>Nibbles</h3> <p>Since frequently the upper and lower 4 bits ('nibble') of a port are @@ -317,46 +297,102 @@ PORTx_low_direction PORTx_high_direction </pre> -<p>This allows nibbles to be used as a regular variables, +This allows nibbles to be used as a regular variables, and also to set pin directions by 4 at a time: <pre> PORTA_high = "7" -- lower nibble remains unchanged PORTA_low_direction = all_output -- direction upper nibble unchanged </pre> -<p>Several function libraries in the Jallib collection use this facility. +Several function libraries in the Jallib collection use this facility. <P>Note: Nibbles are always declared even if the register doesn't have the nibble fully populated (or not populated at all!) with pins. -<h3>Alias names for pins</h3> +<h3>Alias names</h3> + <p>When a pin is multiplexed (has a different function depending on control registers or configuration bit settings), aliases are declared to make the pin accessible by a more functional name. For example: of the 16F88 pin_B6 is usable as analog input for the ADC module as channel 5 and therefore pin_B6 has been given an alias name pin_AN5. -You can find the 'AN5' indication in the datasheet. -<br)Of course also for the pin_B6_direction an alias is declared and +You can find the 'AN5' name in the datasheet. +<br>Of course also for the pin_B6_direction an alias is declared and called similarly pin_AN5_direction! <br>Libraries (for this example the ADC library) will use the alias names in stead of the physical pin names. Another PIC may have pin_AN5 associated with a different physical pin, -but by using the alias names the ADC library becomes indenpent of the +but by using the alias name the ADC library becomes indenpent of the physical pin configuration and and makes it to a large extent device independent. -<p>There are some exceptions. +<p>If you want to use another name for a port, nibble or individual pin +you can also specify an alias in your program. +For example when you have a red LED connected to pin 0 of PortA, you could +specify: +<pre> + alias led_red is pin_A0 +</pre> +and use 'led_red = on' or 'led_red = off' assignments in your program. +<p>Pin aliases in the device files are declared in this +way and therefore also make use of the port shadowing provided by +the device files. +<br<i>This way of aliasing - using the keyword 'alias' - is only +available since JalV2 compiler version 2.4l.</i> + +<p>You should <b>avoid direct pin and I/O port manipulation</b>, because +it will be overruled by the automatic shadowing mechanism +(see the chapter about <A href="#ch_shadowing">Shadowing</a>). +For example +do <b>not</b> specify: +<pre> + var bit led_red at portA : 0 +</pre> +With this specification a 'led-red = on' will have the desired result, but +it will not update the shadow register. +Any next operation which uses the shadowing mechanism will override the +previous direct control operation. + +<p>Some pin alias names are not acceptable for the JalV2 compiler, in +which a special name is used. +For example PICs with USB support have a D+ and D- pin. +These are declared (for the 18F4550) as: +<pre> + alias pin_D_POS is pin_C5 + alias pin_D_NEG is pin_C4 +</pre> Some function pins can be on one or another pin of a PIC, controlled by a register or a configuration bit setting. In these cases the name has to be suffixed to prevent duplicate names. The 16F737 for example can have the CCP2 bit on pin_B3 or pin_C1, controlled by a configuration bit (fuse_def CCP2MUX). <pre> - var volatile bit pin_CCP2_RB3 is pin_B3 - var volatile bit pin_CCP2_RC1 is pin_C1 + alias pin_CCP2_RB3 is pin_B3 + alias pin_CCP2_RC1 is pin_C1 </pre> The program or library has to detect the actual use of the CCP2 pin. +<h3>Non-memory-mapped registers</h3> +<p>Some PICs, mainly in the baseline series, are missing some +addressable ('memory mapped') registers. +For example the 12-bit core PICs (10Fs, 12F5x, etc) have no memory +mapped TRISx registers, in stead these PICs have a TRISx instruction to +set the direction of ports or pins. +This would make it impossible for function libraries and application +programs to use statements like: +<pre> + PORTA_direction = all_output +</pre> +The device files contain pseudo variables which mimic the existence +of memory mapped registers. +This makes it possible to use statements like the one above. +<p>For example: even though a 16F59 has no addressable TRISC register, +you can still specify: +<pre> + pin_C5_direction = output +</pre> + + <h3>Names of MSSP registers</h3> <p>Names of registers of MSSP modules have been normalized as follows: <ul> @@ -461,36 +497,44 @@ So an ADC library can always address the variable ADCONx_CHS as multibit 'binary' field, regardless if the bits are scattered over the register or not. + <h3>Names of Timer fields</h3> -<p>For the timers the following naming has been chosen: +<p>Some register subfields of timer control registers have inconsistent +names in the MPLAB .dev files. +<p>For these subfields the following naming convention has been chosen: <ul> -<li>'bit*4 PS' of T0CON splitted into 'bit PSA' and 'bit*3 PS' -(this is a correction of the MPLAB .dev files). -<li>Bit TxSYNC in TxCON register normalized to NTxSYNC for: +<li>The interrupt bits of Timer 0 are declared as TMR0IE and TMR0IF + for <b>all</b> devices, even though some datasheets use the names + T0IE and T0IF. +<li>Bit TxSYNC in TxCON register is normalized to NTxSYNC for: <ul> <li>T1CON of baseline and midrange <li>T1CON, T3CON, T5CON and T7CON of 18F series. </ul> <li>TxCON_TOUTPS is normalized to TxCON_TxOUTPS (x = timer number) for -the 18Fs. -Since the baseline PICs have only 1 timer with TOUTPS bit this name has -been maintained. + the 18Fs. + Since the midrange PICs have only 1 timer with TOUTPS bit this name + has been maintained. +<li>'bit*4 PS' of T0CON splitted into 'bit PSA' and 'bit*3 PS' </ul> + <h3>Miscellaneous remarks about names</h3> -<p>When you have used JAL before with other device files or libraries -you may notice some more differences in the naming convention: <ul> -<li>PORTA is used consistently, while previously PORT_A was a - popular naming convention especially for PORT_A_low/high, +<li>The name PORTA (and a similar name for other ports) is used + consistently, while previously PORT_A was a popular naming + convention especially for PORT_A_low, PORT_A_high, PORT_A_direction, etc. - For individual pins the convention 'pin_Ax' is used. -<li>When you hit compile errors related to undefined names, scan the - device files to search for the Jallib name of the register. +<li>For individual pins the convention 'pin_Ax' is used. +<li>Numerous minor naming inconsistences in the MPLAB .dev files + are 'corrected'. </ul> +When you hit compilation errors related to undefined names, scan the +device file of the used PIC to search for the Jallib name of the +registers and their subfields. -<h2>About Port Shadowing</h2> +<h2><a name="ch_shadowing">About Port Shadowing</a></h2> <p>Port shadowing is a technique to prevent the Read-Modify-Write ('RMW') problem with I/O ports of PICmicro's. @@ -505,7 +549,7 @@ <p>With port shadowing for the baseline and midrange PICs (10F, 12F, 16F) a RAM location is used as replacement for the port for output. -The 18F series have a special register for this purpose (LATx). +<p>The 18F series have a special register for this purpose (LATx). Although the techniques are slightly different, the general rules are: reading is done from the port directly, while writing is done to the shadow register of which the contents is subsequently passed to the @@ -526,39 +570,6 @@ Portx_low is read from or written to bits 3..0 of Portx, Portx_high is read from or written to bits 7..4 of Portx. -<p>If you want to use other names for ports, nibbles or individual pins -you must specify an alias. -For example when you have a red LED connected to pin 0 of PortA, you could -specify: -<pre> - var bit led_red is pin_A0 -</pre> -and use 'led_red = on' or 'led_red = off' in your program. - -<p><B>Note: the pin aliases in the device files are declared in this -way and therefore are also make use of the port shadowing provided by -the device files.</b> - - -<p>You should <b>avoid direct pin and I/O port manipulation</b>, because -it will be overruled by the automatic shadowing mechanism. For example -do <b>not</b> specify: -<pre> - var bit led_red at portA : 0 -</pre> -With this specification a 'led-red = on' will have the desired result, but -it will not update the shadow register. -Any next operation which uses the shadowing mechanism will override the -previous direct control operation. - -<p>Shadowing is also bypassed when you initialise the alias with the -declaration. -So declaring and initialising an alias as follows: -<pre> - var bit led_red is pin_A0 = off -</pre> -is bad practice! -Initialize an alias separatedly after the declaration. <h2>Naming convention for configuration bits (fuses)</h2> --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "jallib" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/jallib?hl=en -~----------~----~----~----~------~----~------~--~---
