Revision: 1470 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) --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
