[jallib] r1470 committed - deivicefiles documentation update...
jal...@googlecode.com
Author: robhamerling
Date: Sun Nov 8 12:11:46 2009
Log: deivicefiles documentation update
(the chapter about pragma fuse_def anticipates on a major revision of the
fuse_def declarations with
dev2jal script version 0.0.86)
http://code.google.com/p/jallib/source/detail?r=1470
Modified:
/trunk/doc/html/devicefiles.html
=======================================
--- /trunk/doc/html/devicefiles.html Thu Nov 5 04:00:23 2009
+++ /trunk/doc/html/devicefiles.html Sun Nov 8 12:11:46 2009
@@ -179,7 +179,7 @@
<h2>Sample program</h2>
<p>The device files define static device (PICmicro) specific matter.
-This allows writing elementary programs, such as for a blinking LED, which
+This allows writing elementary programs, such as for a blinking led, which
are almost device independent.
Differences are mostly in the fuse settings.
@@ -187,7 +187,7 @@
libraries for more complicated functions like displaying text on an LCD
display or handling analog devices.
-<p>Below a simple blink-an-LED program (LED on pin 1 of Port A) for a
+<p>Below a simple blink-a-led program (led on pin 1 of port A) for a
PIC16F886 using a 20 MHz resonator.
In addition to the device-specific information obtained from the include
file '16f886.jal' some run-time information is needed, like the speed and
@@ -195,7 +195,7 @@
No extra function libraries are required.
<pre>
--- ------ Blink-an-LED on pin A1 of a PIC16F886 --------
+-- ------ blink-a-led on pin_A1 of a PIC16F886 --------
include 16f886 -- target is a PIC16F886
-- Notes: - The extension .jal is
@@ -215,7 +215,7 @@
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
+ led_direction = output -- make led-pin output
forever loop -- endless loop
led = on -- there is light!
_usec_delay(250000) -- spin 1/4 seconds
@@ -224,7 +224,7 @@
end loop
</pre>
-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>
@@ -327,7 +327,7 @@
<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
+For example when you have a red led connected to pin 0 of PortA, you could
specify:
<pre>
alias led_red is pin_A0
@@ -649,37 +649,122 @@
<h2>Naming convention for configuration bit fields (fuses)</h2>
-<p>The configuration bits or groups of bits is such a large variety that it
-is almost impossible to obtain a uniform naming convention.
-<ul>
-<li>For all implemented configuration bits or bit fields an option name and
-two or more values are defined, but the chosen names may not always be
-intuitive or convenient.
-Some names or keywords are very long!
-<li>When the compiler stalls over a fuse-def line a correction should
-be applied.
+<h3>Pragma fuse_def</h3>
+<p>The MPLAB .dev files contain a <b>keyword</b> for every configuration
+bit or group of bits,
+and a <b>description</b> of the possible bit settings.
+Unfortunately not always the same keyword is used for essentially the same
+configuration bit or bit-field, and the keyword is sometimes different from
+the keyword in the datasheet, or is simply spelled wrongly!
+The descriptions have an even larger variation and are sometimes very long.
+For use with Jal, in particular for the 'pragma fuse_def' declarations,
+a consistent keyword and a single-word keyword-value is desired.
+The Jallib 'standard' is described below.
+
+<h3>Fuse_def keywords, synonyms and replaced words</h3>
+<p>For all pragma fuse_defs a keyword and
+a number of symbolic values are declared in the device files.
+
+<p>Every configuration word or byte is preceeded with a comment line
+indicating its address in memory.
+<br>The meaning of configuration bits can in most cases be found in the
+DataSheet of the specific chip, in the section 'Special Features of the
+CPU'.
+This info can also be found in the Programming Specifications of the chip.
+For convenience the MicroChip document numbers of the specific PIC are
+mentioned in the heading of its device file.
+
+<p>To minimize misunderstanding and confusion the desription for every
+keyword as found in the MPLAB .dev file is appended as comment on the
+'pragma fuse_def' line.
+The combination of memory address and description should unambiguously
+identify which which configuration bit(s) are controlled by the keyword,
+even though the name might be different from that in the datasheet.
+
+<p>Where convenient and intuitive enough the keywords found in the MPLAB
+.dev files is used.
+But synonyms are eliminated and some apparent misspellings are
+corrected.
+Sometimes an arbitrary keyword is chosen.
+
+<p>The list below shows examples of most deviations of keywords from
MPLAB .dev files:
+
+<table>
+<tr><th>keyword </th><th>replaces synonym(s) and typo(s)</th></tr>
+<tr><th>BBSIZ </th><td>BBSIZE0 </td></tr>
+<tr><th>BROWNOUT</th><td>BODEN, BOREN, DSBOREN </td></tr>
+<tr><th>CCPxMUX </th><td>CCPxMX </td></tr>
+<tr><th>CPD </th><td>CPDF, CPSW </td></tr>
+<tr><th>CPx </th><td>CP_x </td></tr>
+<tr><th>DEBUG </th><td>BACKBUG, BKBUG </td></tr>
+<tr><th>EBRTx </th><td>EBRTx (typo) </td></tr>
+<tr><th>EBTRx </th><td>EBTR_x </td></tr>
+<tr><th>ECCPMUX </th><td>ECCPMX </td></tr>
+<tr><th>FLTAMUX </th><td>FLTAMX </td></tr>
+<tr><th>OSC </th><td>FOSC </td></tr>
+<tr><th>IOSCFS </th><td>IOFSCS (typo) </td></tr>
+<tr><th>MCLR </th><td>MCLRE </td></tr>
+<tr><th>MSSPMASK</th><td>MSSP7B_EN, MSSPMSK </td></tr>
+<tr><th>PMODE </th><td>PM </td></tr>
+<tr><th>PWM4MUX </th><td>PWM4MX </td></tr>
+<tr><th>PWRTE </th><td>PUT, PWRT, PWRTEN, NPWRTE, NPWRTEN</td></tr>
+<tr><th>RTCOSC </th><td>RTCSOSC </td></tr>
+<tr><th>SOSCSEL </th><td>SOSCEL </td></tr>
+<tr><th>SSPMUX </th><td>SSPMX </td></tr>
+<tr><th>STVR </th><td>STVREN </td></tr>
+<tr><th>T1OSCMUX</th><td>T1OSCMX </td></tr>
+<tr><th>T2CMUX </th><td>T2CMX </td></tr>
+<tr><th>VOLTAGE </th><td>BODENV, BOR4V, BORV </td></tr>
+<tr><th>WDT </th><td>WDTEN </td></tr>
+<tr><th>WRT </th><td>WRT_ENABLE </td></tr>
+<tr><th>WRTx </th><td>WRT_x </td></tr>
+</table>
+Notes:
+<ol>
+<li>Multiplexing keywords end in 'MUX', not 'MX'.
+<li>Coupling undercore characters are removed.
+<li>Not all declared keywords in the MPLAB .dev files may be 'catched',
+there may be some inconveniently long keywords left.
+<li>When the compiler stalls over a fuse-def line a correction should be
+applied.
If you encounter such an occasion please report it in the Jallib
discussion group at Google Groups or Jallist at Yahoo! groups.
-<li>For the most frequently used configuration bits a 'standard' option
-name is defined, along with a 'standard' tag, see the list below.
-</ul>
-
-<p>Only for the oscillator specification the MPLAB information files
contain
-more than 140 different descriptions!
-Because of synonyms this number could be normalized to a much smaller
-number!
-The first part is the oscillator type, the [optional] second part indicates
-a related subfunction.
-For example it may indicate if the OSC2 pin is CLKOUT or I/O, or if PLL is
-active for the 18F series.
-Descriptions in MPLAB which do not fit in the normalization scheme are
copied
-almost literally.
-
-<p>
-
-<p>Below the 'normalized' fuse_defs:
-
-<h3>Fuse_def BBSIZ (Boot Block Size)</h3>
+</ol>
+
+<h3>Fuse_def symbolic values</h3>
+<p>As mentioned above the MPLAB .dev files contain frequently long and
+descriptions with many variations of the same story.
+Only for the oscillator specification alone the MPLAB .dev files contains
+almost 200 different descriptions!
+
+<p>Often the description is a single word like DISABLED or ACTIVE,
+but many descriptions contain multiple words.
+These have to be reduced to a single word or at least a single string
+(multiple words coupled by underscore characters)
+
+<p>Like for the keywords also for the symbolic values many synonyms can be
+found in the MPLAB .dev files.
+These synonyms are eliminated as much as possible.
+For example 'ENABLE' is often used even when the device file specifies 'ON'
+or 'ACTIVE'.
+
+<p>Below a set of 'normalized' pragma fuse_def:
+
+<h4>Fuse_def ADSEL (ADC resolution)</h3>
+<pre>
+ B10 -- 10 bits
+ B12 -- 12 bits
+ B.. -- other number of bits
+</pre>
+
+<h4>Fuse_def ABW (Address Bus Width)/h3>
+<pre>
+ B8 -- 8 bits
+ B16 -- 16 bits
+ B.. -- other number of bits
+</pre>
+
+<h4>Fuse_def BBSIZ (Boot Block Size)</h3>
<pre>
W256 -- 256 words
W512 -- 512 words
@@ -688,7 +773,14 @@
W... -- any other number of words
</pre>
-<h3>Fuse_def BROWNOUT (Brown Out detection)</h3>
+<h4>Fuse_def BG (Band Gap)/h3>
+<pre>
+ ADJUST_NEG -- negative adjustment
+ ADJUST_POS -- positive adjustment
+ ... -- other
+</pre>
+
+<h4>Fuse_def BROWNOUT (Brown Out detection)</h3>
<pre>
ENABLED -- BOD enabled, SBOREN disabled
RUNONLY -- BOD enabled in run, disabled in sleep
@@ -697,29 +789,48 @@
</pre>
BROWNOUT is also used for Deep Sleep BrownOut (DSBOREN).
-<h3>Fuse_def CCPxMUX (multiplexing of pin of CCP module x)</h3>
+<h4>Fuse_def BW (Bus Width)/h3>
+<pre>
+ B8 -- 8 bits
+ B16 -- 16 bits
+ B.. -- other number of bits
+</pre>
+
+<h4>Fuse_def CCPxMUX (multiplexing of pin of CCP module x)</h3>
<pre>
pin_xy -- assigned to pin y of PORTx
pin_.. -- any other
</pre>
-The keyword 'CCPxMUX' is used even when the datasheet may specify 'CCPxMX'.
<br>When the multiplexing is also dependend of the microprocessor mode
(with some high end 18Fs) the pin for 'Microcontroller mode' is specified.
-Of course in other modes the other alternate pin will actually be
configured!
-
-<h3>Fuse_def CP (Code Protection)</h3>
+Of course in other modes another alternate pin will actually be configured!
+
+<h4>Fuse_def CP (Code Protection)</h3>
<pre>
ENABLED -- Code memory read protection on
DISABLED -- Code mewmory read protection off
</pre>
-<h3>Fuse_def CPD (Data Code Protection)</h3>
+<h4>Fuse_def CPD (Data Code Protection)</h3>
<pre>
ENABLED -- Data (EEPROM) memory read protection on
DISABLED -- Data (EEPROM) memory read protection off
</pre>
-<h3>Fuse_def WDTPS and DSWDTPS (Deep Sleep) WatchDog Timer PostScaler</h3>
+<h4>Fuse_def CPUDIV (CPU clock divisor)</h3>
+<pre>
+ P2 -- divide by 2
+ P.. -- etc
+ P6 -- device by 6
+</pre>
+
+<h4>Fuse_def DSWDTOSC (Watchdog oscillator selections)</h3>
+<pre>
+ INTOSC -- internal oscillator
+ OSC -- oscillator determined by OSC fuse_def
+</pre>
+
+<h4>Fuse_def DSWDTPS and WDTPS (Deep Sleep) WatchDog Timer
PostScaler</h3>
<pre>
P2G -- 1 : 2G (2 * 1073741824)
P...
@@ -730,31 +841,61 @@
P2 -- 1 : 2
</pre>
-<h3>Fuse_def FOSC2 (secondary oscillator select)</h3>
+<h4>Fuse_def EBTRB (bootblock write protection)</h3>
+<pre>
+ ENABLED -- boot block table read protected
+ DISABLED -- boot block may be table read
+</pre>
+
+<h4>Fuse_def ECCPxMUX (ECCP pin multiplexing)</h3>
+<pre>
+ pin_xy -- pin y of portx is used
+</pre>
+
+<h4>Fuse_def EMB (External memory bus width)/h3>
+<pre>
+ B12 -- 12 bits
+ B16 -- 16 bits
+ B20 -- 20 bit
+ DISABLED -- disabled
+</pre>
+
+<h4>Fuse_def FLTAMUX (FLTA multiplexing)</h3>
+<pre>
+ pin_xy -- pin y of portx is used
+</pre>
+
+<h4>Fuse_def FOSC2 (default/reset system clock select)</h3>
<pre>
OSC -- Clock selected by OSC setting
INTOSC -- Internal oscillator
</pre>
-<h3>Fuse_def IOSCFS (Internal Oscillator Frequency Select)</h3>
+<h4>Fuse_def HFOFST (...)</h3>
+<pre>
+ ENABLED -- enable
+ DISABLED -- disabled
+</pre>
+
+<h4>Fuse_def IOSCFS (Internal Oscillator Frequency Select)</h3>
<pre>
F4MHZ -- 4 MHz
F8MHZ -- 8 MHz
</pre>
-<h3>Fuse_def LVP (Low Voltage Programming)</h3>
+<h4>Fuse_def LVP (Low Voltage Programming)</h3>
<pre>
- ENABLED -- LVP on, enabled
- DISABLED -- LVP off, disabled
+ ENABLED -- LVP on
+ DISABLED -- LVP off
</pre>
-<h3>Fuse_def MCLR (reset)</h3>
+<h4>Fuse_def MCLR (reset)</h3>
<pre>
EXTERNAL -- /MCLR pin enabled
INTERNAL -- /MCLR pin is digital I/O
</pre>
-<h3>Fuse_def OSC (oscillator)</h3>
+<h4>Fuse_def OSC (oscillator)</h3>
<pre>
LP -- Low Power crystal on OSC1,OSC2
XT -- Crystal or Resonator on OSC1,OSC2
@@ -769,7 +910,11 @@
INTOSC_CLKOUT -- Internal oscillator, OSC1 is I/O, ClockOut on OSC2
INTOSC_NOCLKOUT -- Internal oscillator, OSC1 and OSC2 are I/O
</pre>
-Several other keywords could be possible, for example for PICs:
+The first or only part is the oscillator type, the [optional] second part
+indicates a related subfunction.
+For example it may indicate if the OSC2 pin is CLKOUT or I/O, or if PLL is
+active.
+Several other keywords are possible, for example:
<ul compact>
<li>with USB
<li>with dual oscillator sources
@@ -778,20 +923,45 @@
The datasheet will specify the possibilities, scan the device files for
the applicable keyword.
-<h3>Fuse_def PWRTE (Power-up Timer Enable)</h3>
+<h4>Fuse_def PLLDIV (PLL prescaler)</h3>
+<pre>
+ P1 -- 1 : 1
+ P.. -- etc
+ P12 -- 1 : 12
+</pre>
+
+<h4>Fuse_def PWRTE (Power-up Timer Enable)</h3>
<pre>
ENABLED -- Power up timer enabled
DISABLED -- Power Up timer disabled
</pre>
-<h3>Fuse_def VCAPEN (Voltage regulator capacitor pin)</h3>
+<h4>Fuse_def T1OSCMUX (Timer 1 multiplexing)</h3>
+<pre>
+ pin_A6_A7 -- pin_A6 and pin_A7 are used
+ pin_B2_B3 -- pin_B2 and pin_B3 are used
+</pre>
+
+<h4>Fuse_def USBDIV (USB clock selection)</h3>
+<pre>
+ P1 -- no divide
+ P2 -- divide by 2
+</pre>
+
+<h4>Fuse_def USBPLL (USB PLL source)</h3>
+<pre>
+ USB -- USB (96 MHz)
+ OSC -- OSC (oscillator)
+</pre>
+
+<h4>Fuse_def VCAPEN (Voltage regulator capacitor pin)</h3>
<pre>
DISABLED
pin_A0
<i>... etc (other pins which could be assigned</i>
</pre>
-<h3>Fuse_def VOLTAGE (Brown out voltage)</h3>
+<h4>Fuse_def VOLTAGE (Brown out voltage)</h3>
<pre>
V20 -- 2.0 Volt
V27 -- 2.7 Volt
@@ -800,19 +970,31 @@
<i>... etc (whatever voltages are applicable)</i>
</pre>
-<h3>Fuse_def WDT (WatchDog Timer)</h3>
+<h4>Fuse_def WAIT (Wait ...)</h3>
+<pre>
+ ENABLED -- synchronous
+ DISABLED -- asynchronous
+</pre>
+
+<h4>Fuse_def WDT (WatchDog Timer)</h3>
<pre>
ENABLED -- Watchdog enabled
DISABLED -- Watchdog disabled
</pre>
-<h3>Fuse_def WDTCS (WatchDog Timer Clock Select)</h3>
+<h4>Fuse_def WDTCS (WatchDog Timer Clock Select)</h3>
<pre>
STANDARD
LOW_POWER
</pre>
-<h3>Fuse_def WPFP (Write Protect Flash Page)</h3>
+<h4>Fuse_def WPEND (Write protect area)</h3>
+<pre>
+ P0_WPFP -- from page 0 to write protect page
+ PWPFD_END -- from write protect page to end of memory
+</pre>
+
+<h4>Fuse_def WPFP (Write Protect Flash Page)</h3>
<pre>
P0 -- Write protect flash page 0
P1 -- Write protect flash page 1
@@ -820,7 +1002,7 @@
P127 -- Write protect flash page 127
</pre>
-<h3>Fuse_def WRT (Program Memory Self-Write Protection)</h3>
+<h4>Fuse_def WRT (Program Memory Self-Write Protection)</h3>
<pre>
NO_PROTECTION -- All program memory writable
ALL_PROTECTED -- Writing of program memory prohibited
@@ -828,24 +1010,9 @@
-- <i>(only specific ranges can be write
protected)</i>
</pre>
-<p><b>Notes:</b>
+Notes:
<ol>
-<li>Every configuration word or byte is preceeded with a comment line
-indicating its address in memory.
-And every individual fuse_def is preceeded with a description to
-identify it.
-The combination should be unambiguous which fuse)def is controlling which
-configuration bit(s), even though the name may be different from that in
the
-datasheet.
-<br>The meaning of configuration bits can in most cases be found in the
-DataSheet of the specific chip, in the section 'Special Features of the
-CPU'.
-This info can also be found in the Programming Specifications of the chip.
-For your convenience the MicroChip document numbers are mentioned in the
-heading of the device files.
-<li>The terms 'Enabled' and 'Disabled' may have to be specified where
-usually 'On' and 'Off' are used.
-<li>In addition to the fuse_defs listed above there may be others,
+<li>The list above in not exhaustive there may be others,
depending on the features of the specific PICmicro.
To conform to a compiler requirement that names must start with a letter or
an underscore and may not contain special characters and spaces the
@@ -859,10 +1026,6 @@
which can be 'R' for range, 'F' for frequency, 'B' for number of bits,
or 'N' otherwise.
</ul>
-Because the MPLAB .dev files contain sometimes very long descriptions for
-configuration bits some keywords may be rather inconvenient!
-Making these more user friendly is work in progress, with as
-consequence <b>keywords may change from release to release</b>!
<li>As an example of an address range specification for PICs with the
possibility to protect certain code memory areas you may have to specify:
<pre>
@@ -874,7 +1037,6 @@
suitable for your application!
</ol>
-
<h2>Alternate ways to specify configuration bits</h2>
<p>When you find the specification of fuse_def inconvenient or
you want to specify the bits one-by-one by yourself, the compiler
@@ -900,7 +1062,7 @@
variety of configuration bits that explicit specification is probably
the best way to make sure all configuration bits are set correctly for
your program.
-As an example see the following list for a simple blink-a-LED program
+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)