Author: robhamerling
Date: Mon Jul 20 08:38:26 2009
New Revision: 1108
Modified:
trunk/CHANGELOG
trunk/doc/html/devicefiles.html
Log:
Update for changes in device files (dev2jal script version 0.0.73)
Modified: trunk/CHANGELOG
==============================================================================
--- trunk/CHANGELOG (original)
+++ trunk/CHANGELOG Mon Jul 20 08:38:26 2009
@@ -15,10 +15,11 @@
- Several corrections for 12F519: PORTB -> GPIO/PORTA, TRISB -> TRISIO,
controlling T0CS bit in enable_digital_io(), flash-data -> EEPROM.
- Added pseudo variable ADCON0_CHS for 16F7x7 with 'splitted' CHS bits.
- - Added declaration of pin_A3,1,0 to 18F13/14K50 and their LF variants.
+ - Added declaration for pin_A3,1,0 to 18F13/14K50 and their LF variants.
- Removed fuse_def statements for ENICPORT and for some unsupported bits
of the 18Fs (protection bits of not present code/data/write memory).
- Added: const byte ADC_NTOTAL_CHANNEL = <number> (of ADC channels)
+ - Revised fuse_def OSC: now handled by table.
- Minor changes in output formatting (for html doc generation).
Modified: trunk/doc/html/devicefiles.html
==============================================================================
--- trunk/doc/html/devicefiles.html (original)
+++ trunk/doc/html/devicefiles.html Mon Jul 20 08:38:26 2009
@@ -132,13 +132,13 @@
for different types of PICs, as the following example shows:
<pre>
- include 16f88
+ include 16f88
- if (target_chip == PIC_16F88) then -- (not for 16f87)
+ if (target_chip == PIC_16F88) then -- (not for 16f87)
- .... -- 16F88 unique code
+ .... -- 16F88 unique code
- end if
+ end if
</pre>
<p>By changing the include statement to 16f87 (or any other) the statements
@@ -197,31 +197,31 @@
<pre>
-- ------ Blink-an-LED on pin A1 of a PIC16F886 --------
- include 16f886 -- target is a PIC16F886
- -- Notes: - The extension .jal is
- -- added by the compiler!
- -- - No other includes
needed.
-
- pragma target clock 20_000_000 -- oscillator frequency (in Hz)
- -- required for delays
-
- pragma target OSC HS -- high speed external oscillator
- pragma target WDT Disabled -- watchdog off
- pragma target MCLR External -- external chip reset
- pragma target LVP Disabled -- no low voltage programming
-
- 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
-
- led_direction = output -- make LED-pin output
- forever loop -- endless loop
- led = on -- there is light!
- _usec_delay(250000) -- spin 1/4 seconds
- led = off -- flip (on->off,off->on)
- _usec_delay(250000) -- spin 1/4 seconds
- end loop
+ include 16f886 -- target is a PIC16F886
+ -- Notes: - The extension .jal is
+ -- added by the compiler!
+ -- - No other includes
needed.
+
+ pragma target clock 20_000_000 -- oscillator frequency (in Hz)
+ -- required for delays
+
+ pragma target OSC HS -- high speed external oscillator
+ pragma target WDT Disabled -- watchdog off
+ pragma target MCLR External -- external chip reset
+ pragma target LVP Disabled -- no low voltage programming
+
+ 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
+
+ led_direction = output -- make LED-pin output
+ forever loop -- endless loop
+ led = on -- there is light!
+ _usec_delay(250000) -- spin 1/4 seconds
+ led = off -- flip (on->off,off->on)
+ _usec_delay(250000) -- spin 1/4 seconds
+ end loop
</pre>
@@ -236,7 +236,7 @@
infrequently use different names for the same entity!
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 the datasheets!
+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.
@@ -245,7 +245,7 @@
also the individual bits or groups of bits are declared.
<br>Subfields of registers have the name of the register as prefix, like
<pre>
- var volatile bit INTCON_GIE at INTCON : 7
+ var volatile bit INTCON_GIE at INTCON : 7
</pre>
<br>Some aliases are declared for easy migration or conversion of
existing JalV2 libraries and programs to the Jallib environment.
@@ -265,11 +265,11 @@
<p>For all ports and port pins a device independent alias is declared and a
similar direction declaration, as the following examples show:
<pre>
- var volatile byte PORTA at <addr>
- var volatile byte TRISA at <addr>
- var volatile byte PORTA_direction at TRISA
- var volatile bit pin_A0 at PORTA : 0
- var volatile bit pin_A0_direction at TRISA : 0
+ var volatile byte PORTA at <addr>
+ var volatile byte TRISA at <addr>
+ var volatile byte PORTA_direction at TRISA
+ 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)
@@ -278,13 +278,13 @@
the device files contain aliases for these.
So even with the smaller PICs you can use the names PORTA, pin_A0, etc.
<pre>
- var volatile byte GPIO at <addr>
- var volatile byte PORTA at GPIO
- var volatile byte TRISIO at <addr>
- var volatile byte TRISA at TRISIO
- var volatile byte PORTA_direction at TRISIO
- var volatile bit pin_A0 at GPIO : 0
- var volatile bit pin_A0_direction at TRISIO : 0
+ var volatile byte GPIO at <addr>
+ var volatile byte PORTA at GPIO
+ var volatile byte TRISIO at <addr>
+ var volatile byte TRISA at TRISIO
+ var volatile byte PORTA_direction at TRISIO
+ 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)
@@ -297,7 +297,7 @@
This would make it impossible for function libraries and application
programs to use statements like:
<pre>
- PORTA_direction = all_output
+ PORTA_direction = all_output
</pre>
<p>The device files contain pseudo variables which mimic the existence
of memory mapped registers,
@@ -305,17 +305,17 @@
<p>For example: even though a 16F59 has no addressable TRISC register,
you can still specify:
<pre>
- pin_C5_direction = output
+ pin_C5_direction = output
</pre>
<h3>Nibbles</h3>
<p>Since frequently the upper and lower 4 bits ('nibble') of a port are
used as a unit, these are declared as pseudo variables.
<pre>
- PORTx_low - bits 0..3
- PORTx_high - bits 4..7
- PORTx_low_direction
- PORTx_high_direction
+ PORTx_low - bits 0..3
+ PORTx_high - bits 4..7
+ PORTx_low_direction
+ PORTx_high_direction
</pre>
<p>This allows nibbles to be used as a regular variables,
and also to set pin directions by 4 at a time:
@@ -351,41 +351,47 @@
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
+ var volatile bit pin_CCP2_RB3 is pin_B3
+ var volatile bit pin_CCP2_RC1 is pin_C1
</pre>
The program or library has to detect the actual use of the CCP2 pin.
-<h3>Names of MSSP modules</h3>
+<h3>Names of MSSP registers</h3>
<p>Names of registers of MSSP modules have been normalized as follows:
<ul>
<li>MSSP module of midrange PICs
<pre>
- SSPADD
- SSPBUF
- SSPCON - first or only control register
- SSPCON2 - second control register (if present)
- SSPSTAT
+ SSPADD
+ SSPBUF
+ SSPCON -- first or only control register
+ SSPCON2 -- second control register (if present)
+ SSPSTAT
</pre>
<li>First or only MSSP module of 18F family:
<pre>
- SSP1ADD
- SSP1BUF
- SSP1CON - first or only control register
- SSP1CON2 - second control register (if present)
- SSP1MASK
- SSP1STAT
+ SSP1ADD
+ SSP1BUF
+ SSP1CON -- first or only control register
+ SSP1CON2 -- second control register (if present)
+ SSP1MASK
+ SSP1STAT
</pre>
<li>Second MSSP module of 18F family
<pre>
- SSP2ADD
- SSP2BUF
- SSP2CON - control register second module
- SSP2CON2 - second control register (if present)
- SSP2STAT
+ SSP2ADD
+ SSP2BUF
+ SSP2CON -- control register second module
+ SSP2CON2 -- second control register (if present)
+ SSP2STAT
</pre>
</ul>
+This naming convention has been chosen because of the differences
+between the midrange and 18F series.
+The libraries for these two groups will be different anyway, so the
+difference in register naming is not issue, on the contrary:
+a compiler message will inform you when you included the wrong library.
+
<h3>Names of ANSEL bits</h3>
<p>For the selection of the ADC channel the ADC library has to set the
@@ -404,20 +410,20 @@
<br>As example below the declaration of ANS bit of the 16F886.
This PIC has as ADC channels 0..4 and 8..13.
<pre>
-var volatile byte ANSEL at { 0x188 }
-var volatile bit JANSEL_ANS4 at ANSEL : 4
-var volatile bit JANSEL_ANS3 at ANSEL : 3
-var volatile bit JANSEL_ANS2 at ANSEL : 2
-var volatile bit JANSEL_ANS1 at ANSEL : 1
-var volatile bit JANSEL_ANS0 at ANSEL : 0
--- ------------------------------------------------
-var volatile byte ANSELH at { 0x189 }
-var volatile bit JANSEL_ANS13 at ANSELH : 5
-var volatile bit JANSEL_ANS12 at ANSELH : 4
-var volatile bit JANSEL_ANS11 at ANSELH : 3
-var volatile bit JANSEL_ANS10 at ANSELH : 2
-var volatile bit JANSEL_ANS9 at ANSELH : 1
-var volatile bit JANSEL_ANS8 at ANSELH : 0
+ var volatile byte ANSEL at { 0x188 }
+ var volatile bit JANSEL_ANS4 at ANSEL : 4
+ var volatile bit JANSEL_ANS3 at ANSEL : 3
+ var volatile bit JANSEL_ANS2 at ANSEL : 2
+ var volatile bit JANSEL_ANS1 at ANSEL : 1
+ var volatile bit JANSEL_ANS0 at ANSEL : 0
+ -- -------------------------------------------------
+ var volatile byte ANSELH at { 0x189 }
+ var volatile bit JANSEL_ANS13 at ANSELH : 5
+ var volatile bit JANSEL_ANS12 at ANSELH : 4
+ var volatile bit JANSEL_ANS11 at ANSELH : 3
+ var volatile bit JANSEL_ANS10 at ANSELH : 2
+ var volatile bit JANSEL_ANS9 at ANSELH : 1
+ var volatile bit JANSEL_ANS8 at ANSELH : 0
</pre>
As you can see the prefix JANSEL is not restricted to bits 0..7 of ANSEL
but is also used for channel numbers higher than 7, controlled by
@@ -427,9 +433,9 @@
JANSEL_ANS20.
<p>Another example for the 10F222:
<pre>
-var volatile byte ADCON0 at { 0x7 }
-var volatile bit JANSEL_ANS1 at ADCON0 : 7
-var volatile bit JANSEL_ANS0 at ADCON0 : 6
+ var volatile byte ADCON0 at { 0x7 }
+ var volatile bit JANSEL_ANS1 at ADCON0 : 7
+ var volatile bit JANSEL_ANS0 at ADCON0 : 6
</pre>
In this case the channel selection bits are in register ADCON0
(the 10Fs have no ANSEL register), but the ADC library doesn't need
@@ -457,8 +463,8 @@
<h3>Miscellaneous remarks about names</h3>
-<p>When you have used Jal before with other device files or libraries
-you may notice some differences in the naming convention:
+<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,
@@ -468,12 +474,13 @@
device files to search for the Jallib name of the register.
</ul>
+
<h2>About Port Shadowing</h2>
<p>Port shadowing is a technique to prevent the Read-Modify-Write
('RMW') problem with I/O ports of PICmicro's.
This is a problem related to its hardware design.
-Search the Internet for "PIC and read-modify-read" and you'll get many
+Search the Internet for "PIC" and "read-modify-read" and you'll get many
hits to more or less interesting articles!
None of the explanations are repeated here.
And you don't absolutely need to understand the problem, since by using
@@ -492,10 +499,10 @@
<p>With the Jallib device files shadowing is automatic, as long
as you use the following names:
<pre>
- PORTx - all bits of port x
- PORTx_low - low order nibble of port x (bits 3..0)
- PORTx_high - high order nibble of port x (bits 7..4)
- pin_xy - single bit 'y' of port 'x'
+ PORTx -- all bits of port x
+ PORTx_low -- low order nibble of port x (bits 3..0)
+ PORTx_high -- high order nibble of port x (bits 7..4)
+ pin_xy -- single bit 'y' of port 'x'
</pre>
(in which 'x' is a port-letter and 'y' a bit number).
<p>Note: The value for both Portx_low and Portx_high is passed with
@@ -509,7 +516,7 @@
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
+ var bit led_red is pin_A0
</pre>
and use 'led_red = on' or 'led_red = off' in your program.
@@ -522,7 +529,7 @@
it will be overruled by the automatic shadowing mechanism. For example
do <b>not</b> specify:
<pre>
- var bit led_red at portA : 0
+ 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.
@@ -533,7 +540,7 @@
declaration.
So declaring and initialising an alias as follows:
<pre>
- var bit led_red is pin_A0 = off
+ var bit led_red is pin_A0 = off
</pre>
is bad practice!
Initialize an alias separatedly after the declaration.
@@ -568,97 +575,97 @@
<h3>Fuse_Def OSC (oscillator)</h3>
<pre>
- LP - Low Power crystal on OSC1,OSC2
- XT - Crystal or Resonator on OSC1,OSC2
- HS - High Speed Crystal or Resonator on OSC1,OSC2
- HS_PLL - as HS, PLL active
- EC_CLKOUT - External Clock (TTL) signal on OSC1, OSC2 is
ClockOut
- EC_NOCLKOUT - External Clock (TTL) signal on OSC1, OSC2 is I/O
- EC_PLL - as EC, PLL active
- RC_CLKOUT - RC oscillator on OSC1, OSC2 is ClockOut
- RC_NOCLKOUT - RC oscillator on OSC1, OSC2 is I/O
- EXTOSC_CLKOUT - External oscillator on OSC1, ClockOut on OSC2
- EXTOSC_NOCLKOUT - External oscillator on OSC1, OSC2 is I/O
- INTOSC_CLKOUT - Internal oscillator, OSC1 is I/O, ClockOut on OSC2
- INTOSC_NOCLKOUT - Internal oscillator, OSC1 and OSC2 are I/O
- (other keywords may be used as well)
+ LP -- Low Power crystal on OSC1,OSC2
+ XT -- Crystal or Resonator on OSC1,OSC2
+ HS -- High Speed Crystal or Resonator on OSC1,OSC2
+ HS_PLL -- HS with PLL active
+ EC_CLKOUT -- External Clock (TTL) signal on OSC1, ClockOut on
OSC2
+ EC_NOCLKOUT -- External Clock (TTL) signal on OSC1, OSC2 is I/O
+ EC_CLKOUT_PLL -- EC_CLKOUT with PLL active
+ EC_NOCLKOUT_PLL -- EC_NOCLKOUT with PLL active
+ RC_CLKOUT -- (external) RC oscillator on OSC1, ClockOut on OSC2
+ RC_NOCLKOUT -- (external) RC oscillator on OSC1, OSC2 is I/O
+ INTOSC_CLKOUT -- Internal oscillator, OSC1 is I/O, ClockOut on OSC2
+ INTOSC_NOCLKOUT -- Internal oscillator, OSC1 and OSC2 are I/O
+ <i>(other keywords may be used as well,
+ esp. for PICs with USB, PLL or dual oscillator sources)</i>
</pre>
<h3>Fuse_Def WDT (watchdog)</h3>
<pre>
- ENABLED - Watchdog enabled
- DISABLED - Watchdog disabled
+ ENABLED -- Watchdog enabled
+ DISABLED -- Watchdog disabled
</pre>
<h3>Fuse_Def WDTPS (Watchdog postscaler)</h3>
<pre>
- P32768 - 1 : 32,768
- P16384 - 1 : 16,384
- P... - 1 : ...
- P.. - 1 : ..
- P2 - 1 : 2
- P1 - 1 : 1
+ P32768 -- 1 : 32768
+ P16384 -- 1 : 16384
+ P... -- 1 : ...
+ P.. -- 1 : ..
+ P2 -- 1 : 2
+ P1 -- 1 : 1
</pre>
<h3>Fuse_Def MCLR (reset)</h3>
<pre>
- EXTERNAL - /MCLR pin enabled
- INTERNAL - /MCLR pin is digital I/O
+ EXTERNAL -- /MCLR pin enabled
+ INTERNAL -- /MCLR pin is digital I/O
</pre>
<h3>Fuse_Def PWRTE (Power-up Timer Enable)</h3>
<pre>
- ENABLED - Power up timer enabled
- DISABLED - Power Up timer disabled
+ ENABLED -- Power up timer enabled
+ DISABLED -- Power Up timer disabled
</pre>
<h3>Fuse_Def BROWNOUT (Brown Out detect)</h3>
<pre>
- ENABLED - BOD enabled, SBOREN disabled
- RUNONLY - BOD enabled in run, disabled in sleep
- CONTROL - SBOREN controls BOR function
- DISABLED - BOD and SBOREN disabled
+ ENABLED -- BOD enabled, SBOREN disabled
+ RUNONLY -- BOD enabled in run, disabled in sleep
+ CONTROL -- SBOREN controls BOR function
+ DISABLED -- BOD and SBOREN disabled
</pre>
<h3>Fuse_Def VOLTAGE (Brown Out voltage)</h3>
<pre>
- V20 - 2.0 Volt
- V27 - 2.7 Volt
- V42 - 4.0 Volt
- V45 - 4.5 Volt
- ... etc (whatever voltages are applicable)
+ V20 -- 2.0 Volt
+ V27 -- 2.7 Volt
+ V42 -- 4.0 Volt
+ V45 -- 4.5 Volt
+ <i>... etc (whatever voltages are applicable)</i>
</pre>
<h3>Fuse_Def LVP (Low Voltage Programming)</h3>
<pre>
- ENABLED - LVP on, enabled
- DISABLED - LVP off, disabled
+ ENABLED -- LVP on, enabled
+ DISABLED -- LVP off, disabled
</pre>
<h3>Fuse_Def CP (Code Protection)</h3>
<pre>
- ENABLED - Code memory read protection on
- DISABLED - Code mewmory read protection off
+ ENABLED -- Code memory read protection on
+ DISABLED -- Code mewmory read protection off
</pre>
<h3>Fuse_Def CPD (Data Code Protection)</h3>
<pre>
- ENABLED - Data (EEPROM) memory read protection on
- DISABLED - Data (EEPROM) memory read protection off
+ ENABLED -- Data (EEPROM) memory read protection on
+ DISABLED -- Data (EEPROM) memory read protection off
</pre>
<h3>Fuse_Def WRT (Program Memory Self-Write Protection)</h3>
<pre>
- NO_PROTECTION - All program memory writable
- ALL_PROTECTED - Writing of program memory prohibited
- Rxxxx_yyyy - Protected memory range
- (only specific ranges can be write protected)
+ NO_PROTECTION -- All program memory writable
+ ALL_PROTECTED -- Writing of program memory prohibited
+ Rxxxx_yyyy -- Protected memory range
+ -- <i>(only specific ranges can be write
protected)</i>
</pre>
<h3>Fuse_Def IOSCFS (Internal Oscillator Frequency Select)</h3>
<pre>
- F4MHZ - 4 MHz
- F8MHZ - 8 MHz
+ F4MHZ -- 4 MHz
+ F8MHZ -- 8 MHz
</pre>
<p><b>Notes:</b>
@@ -667,7 +674,7 @@
depending on the features of the specific PICmicro.
Please read the device file to see which fuse-defs are available for your
target PICmicro.
-<li>The terms 'Enabled' and 'Disabled' may need to be specified where
+<li>The terms 'Enabled' and 'Disabled' may have to be specified where
usually 'On' and 'Off' are used.
</ol>
@@ -698,21 +705,23 @@
As an example see the following list for a simple blink-a-LED program
with an 18F242.
<pre>
- pragma target fuses 0 0b0000_0000 -- (n/a)
- pragma target fuses 1 0b0010_0010 -- not switchable, HS osc, no
PLL
- pragma target fuses 2 0b0000_0001 -- BOR disabled, PWTR disabled
- pragma target fuses 3 0b0000_0000 -- watchdog disabled
- pragma target fuses 4 0b0000_0000 -- (n/a)
- pragma target fuses 5 0b0000_0001 -- CCP2 on RC1
- pragma target fuses 6 0b1000_0001 -- no bg debug, no LVP, STVREN
- pragma target fuses 7 0b0000_0000 -- (n/a)
- pragma target fuses 8 0b0000_1111 -- no code protection
- pragma target fuses 9 0b1100_0000 -- no data protection
- pragma target fuses 10 0b0000_1111 -- no code write protection
- pragma target fuses 11 0b1110_0000 -- no other write protection
- pragma target fuses 12 0b0000_1111 -- no table read protection
- pragma target fuses 13 0b0100_0000 -- no boot block write protect
+ pragma target fuses 0 0b0000_0000 -- (n/a)
+ pragma target fuses 1 0b0010_0010 -- not switchable, HS osc, no
PLL
+ pragma target fuses 2 0b0000_0001 -- BOR disabled, PWTR disabled
+ pragma target fuses 3 0b0000_0000 -- watchdog disabled
+ pragma target fuses 4 0b0000_0000 -- (n/a)
+ pragma target fuses 5 0b0000_0001 -- CCP2 on RC1
+ pragma target fuses 6 0b1000_0001 -- no bg debug, no LVP, STVREN
+ pragma target fuses 7 0b0000_0000 -- (n/a)
+ pragma target fuses 8 0b0000_1111 -- no code protection
+ pragma target fuses 9 0b1100_0000 -- no data protection
+ pragma target fuses 10 0b0000_1111 -- no code write protection
+ pragma target fuses 11 0b1110_0000 -- no other write protection
+ pragma target fuses 12 0b0000_1111 -- no table read protection
+ pragma target fuses 13 0b0100_0000 -- no boot block write protect
</pre>
+(n/a) mean not applicable to this specific PIC, but may be specified
+(as all zeroes).
<p>Notes:
<ol>
@@ -797,8 +806,8 @@
You must remove these bank switching functions from your programs and
libraries!
-<li>The device specific include files are generated from the MPLAB .dev and
-.lkr files.
+<li>The device specific include files are generated from the MPLAB .dev
+and .lkr files.
This may cause confusion or even conflicts because the register and bit
names are not always identical to those in the datasheets!
Apart from that, MPLAB is not errorfree, consequently include files
generated
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
