Revision: 1747
Author: robhamerling
Date: Thu Mar 4 13:12:28 2010
Log: CHANGELOG and devicefiles.html update for 'inline' nibble pseudo
variables
http://code.google.com/p/jallib/source/detail?r=1747
Modified:
/trunk/CHANGELOG
/trunk/doc/html/devicefiles.html
=======================================
--- /trunk/CHANGELOG Mon Mar 1 23:32:30 2010
+++ /trunk/CHANGELOG Thu Mar 4 13:12:28 2010
@@ -7,9 +7,11 @@
device files:
- Added aliases for the first of two USARTs to be able to use the current
(hardware) serial libs
- - Added device files for 16 extended midrange PICS (18/19[L]F18/19xx)
+ - Added device files for 16 extended midrange PICS (12/16[L]F18/19xx)
- Revised memory specifications for _pic_accum and _pic_isr_w for some
PICs
- Added device files for 18f87j50 group of PICs
+ - Added T0CON_T0xx aliases for timer 0 related fields in OPTION_REG of
midrange PICs.
+ - Nibble pseudo variables changed to 'inline' functions/procedures.
externals:
- 23k256 moved "const byte SRAM_23K256_ALWAYS_SET_SPI_MODE = TRUE" from
lib to sample files
=======================================
--- /trunk/doc/html/devicefiles.html Mon Feb 1 12:23:07 2010
+++ /trunk/doc/html/devicefiles.html Thu Mar 4 13:12:28 2010
@@ -9,23 +9,37 @@
<meta name="project" content="This file is part of jallib
http://jallib.googlecode.com";>
<meta name="license" content="Released under the BSD license"
"http://www.opensource.org/licenses/bsd-license.php";>
- <meta name="compiler" content="2.4l">
+ <meta name="compiler" content="2.4n">
<link rel="stylesheet" href="jallib.css" type="text/css">
</head>
<body lang="en-US" dir="LTR">
+<h1>Jallib Device Files Users Guide</h1>
+<p><center>by Rob Hamerling</center>
+
<h2>Table of contents</h2>
<ol>
<li><a href="#intro">Introduction</a>
<li><a href="#overall">The Overall Picture</a>
+ <ul>
+ <li><a href="#device_files">Device files</a>
+ <li><a href="#chipdef_jallib">Common include file Chipdef_Jallib</a>
+ <li><a href="#function_includes">Function include files'</a>
+ </ul>
<li><a href="#user">User Information</a>
+ <ul>
+ <li><a href="#sample_program">Sample Program</a>
+ <li><a href="#ports_and_pins">Naming conventions for ports and pins</a>
+ <li><a href="#peripherals">Names for function modules and peripherals</a>
+ <li><a href="#shadowing">About port shadowing</a>
+ <li><a href="#osccal">About OSCCAL</a>
+ <li><a href="#fuses">Naming convention for configuration bit fields
(fuses)</a>
+ <li><a href="#compiler">Compiler requirements</a>
+ </ul>
<li><a href="#gen">Generating device files</a>
</eol>
-<h1>1. Jallib Device Files Users Guide</h1>
-<p><center>by Rob Hamerling</center>
-
-<h1><a name="intro">Introduction</a></h1>
+<h1><a name="intro">1. Introduction</a></h1>
<p>When I started programming in JAL it struck me that there were so few
JALV2 include files, in particular not for some of my favourite PICmicros
@@ -65,7 +79,8 @@
supplemented and corrected with information from the datasheets.
<hr>
-<h1><a name="overall">The Overall Picture</a></h1>
+<h1><a name="overall">2. The Overall Picture</a></h1>
+
<p>With the design of the device files I had in mind a structure as shown
below.
<pre>
@@ -85,11 +100,11 @@
</pre>
<p>These device files are now part of the central JalV2 library
-repository <a href="http://jallib.googlecode.com/";>JalLib</a> at
-code.google.com, which uses the same structure.
+repository <a href="http://jallib.googlecode.com/";>Jallib</a> at
+<b>GoogleCode</b>, which uses the same structure.
-<h2>Device Files</h2>
+<h2><a name="device_files">Device Files</a></h2>
<p>The device files are the base for other include files and contain:
<ul>
@@ -113,16 +128,16 @@
etc.
Required changes are the responsibility of the application program or
function libraries.
-For convenience reasons every device file contains a procedure to
+For user convenience every device file contains a procedure to
disable all analog modules of the PIC and to change all pins which are
-analog by default to digital I/O: enable_digital_io().
+by default analog to digital I/O: enable_digital_io().
<p>The defaults for the configuration bits may be slightly different
than their specifications in the datasheet.
You can find the default configuration bits settings in the top of the
device file.
-<h2>Common Include File 'chipdef_jallib.jal'</h2>
+<h2><a name="chipdef_jallib">Common Include
File 'chipdef_jallib.jal'</a></h2>
<p>The file 'chipdef_jallib.jal' which comes with these device files
replaces the file 'chipdef.jal' which comes with the compiler distribution.
@@ -161,7 +176,7 @@
Therefore it had to be replaced when using this set of device files.
-<h2>Function Include Files</h2>
+<h2><a name="function_includes">Function Include Files</a></h2>
<p>Function specific include files offer facilities to ease the use of
PIC peripherals (such as USART, ADC), external devices (such as LCDs,
@@ -181,9 +196,14 @@
<hr>
-<h1><a name="user">User Information</a></h1>
-
-<h2>Sample program</h2>
+<h1><a name="user">3. User Information</a></h1>
+
+<p>We'll start with a very elementary sample program (blink-a-led) to show
+how device files make programming in JAL a piece of cake,
+followed by a description of other features of the device files which are
+aimed at writing device independent libraries.
+
+<h2><a name="sample_program">Sample program</a></h2>
<p>The device files define static device (PICmicro) specific matter.
This allows writing elementary programs, such as for a blinking led, which
@@ -209,15 +229,15 @@
-- added by the compiler!
-- - No other includes
needed.
- pragma target clock 20_000_000 -- oscillator frequency (in Hz)
+ 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)
+ 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() -- set all pins to digital I/O
alias led is pin_A1 -- declare alias for pin_A1
alias led_direction is pin_A1_direction -- and for its direction
@@ -231,13 +251,13 @@
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 a led connected
(with series resistor!) to pin 3 (RA1) should blink twice a second.
-<h2>Naming conventions for Ports and Pins</h2>
-
-<p>Unfortunately MPLAB of Microchip is not particularly consistent in its
-choice of names!
+<h2><a name="ports_and_pins">Naming conventions for Ports and Pins</a></h2>
+
+<p>Unfortunately MPLAB of Microchip is not particularly consistent in
+its choice of names!
The datasheets and the various informational files in MPLAB not
infrequently use different names for the same entity!
As a rule the device files use the names as used by the datasheets.
@@ -344,13 +364,12 @@
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>
+available since JalV2 compiler version 2.4n.</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:
+For example do <b>not</b> specify:
<pre>
var bit led_red at portA : 0
</pre>
@@ -383,7 +402,7 @@
With the 18F8310 for example the the multiplexing depends also on the
processor mode.
One position of CCP2 is pin_C1, the alternate pin is pin_E7
-(in Microcontroller mode) of pin_B3 (in Microprocessor,
+(in Microcontroller mode) or pin_B3 (in Microprocessor,
Extended Microcontroller and Microcontroller with Boot Block modes).
This variant is not always available in the current device files!
@@ -417,6 +436,8 @@
automatically (and reset afterwards).
+<h2><a name="peripherals">Names of functions modules</a><h2>
+
<h3>Names of MSSP registers</h3>
<p>Names of registers of MSSP modules have been normalized as follows:
<ul>
@@ -489,9 +510,12 @@
<tr><td>ECCPRxH <td>CCPRxH <td> </tr>
<tr><td>ECCPRxL <td>CCPRxL <td> </tr>
</table>
-<p>Exception: for PICs with both an CCP1CON and a ECCP1CON register
-(18f448,4480,458,4580,4585,4680,4682,4685),
-and to allow the enhanced CCP module to be used as second legacy CCP
module,
+<p>Extended midrange PICs (12/16F18/19xx) have only enhanced CCP modules
+which have 'legacy' names.
+Therefore no special naming is needed to use these as legacy CCP modules.
+<p>For PICs with both an CCP1CON and a ECCP1CON register
+(18f448,4480,458,4580,4585,4680,4682,4685)
+to allow the enhanced CCP module to be used as second legacy CCP module
the following aliases are declared:
<table>
<tr><th>field <th>alias <th>remarks </tr>
@@ -639,9 +663,9 @@
<p>For these subfields the following naming convention has been chosen:
<ul>
<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
+ for <b>all</b> PICs, even though some datasheets use the names
T0IE and T0IF.
-<li>Bit TxSYNC in TxCON register is normalized to NTxSYNC for:
+<li>Bit TxSYNC in TxCON registers is normalized to NTxSYNC for:
<ul>
<li>T1CON of baseline and midrange
<li>T1CON, T3CON, T5CON and T7CON of 18F series.
@@ -650,7 +674,17 @@
the 18Fs.
Since the midrange PICs have only 1 timer with TOUTPS bit this name
has been maintained for these PICs.
-<li>'bit*4 PS' of T0CON splitted into 'bit PSA' and 'bit*3 PS'
+ Extended midrange PICs have T2CON, T4CON and T6CON and
+ follow the same naming convention.
+<li>A variable 'bit*4 PS' in T0CON is splitted in 'bit PSA' and 'bit*3 PS'
+<li>Aliases are provided for Timer 0 related fields in OPTION_REG
+ of baseline and midrange PICS to simulate the existence of a T0CON
+ register - like there are T0CON, T1CON, T2CON, etc. registers
+ with other PICs: T0CON_T0SE, T0CON_T0CS, T0CON_PSA and T0CON_T0PS.
+<li>The extended midrange PICs have in OPTION_REG the bits TMR0CS1 and
+ TMR0CS0 and a 2-bits prescaler TMR0PS.
+ These have been given aliases bit*2 T0CON_T0CS and bit*2 T0CON_T0PS
+ to be as much compatible as possible with the other midrange PICs.
</ul>
@@ -669,7 +703,7 @@
registers and their subfields.
-<h2><a name="ch_shadowing">About Port Shadowing</a></h2>
+<h2><a name="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.
@@ -705,7 +739,7 @@
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.
-<h2><a name="ch_osccal">About OSCCAL</a></h2>
+<h2><a name="osccal">About OSCCAL</a></h2>
<p>A number of low end PICS have a reserved word in high memory, provided
by
the manufacturer, which contains information for calibration of the
internal
@@ -736,7 +770,7 @@
-<h2>Naming convention for configuration bit fields (fuses)</h2>
+<h2><a name="fuses">Naming convention for configuration bit fields
(fuses)</a></h2>
<h3>Pragma fuse_def</h3>
<p>The MPLAB .dev files contain a <b>keyword</b> for every configuration
@@ -1249,42 +1283,52 @@
<hr>
-<h2>Compiler requirements</h2>
-
-<p>The compiler - at the moment of this writing version 2.4l - has a
+<h2><a name="compiler">Compiler requirements</a></h2>
+
+<p>The compiler - at the moment of this writing version 2.4n - has a
number of requirements for device specifications.
The most important from a user perspective are the following:
<h3>Memory allocation</h3>
-<p>The device files specify the amounts of available shared and unshared
-memory (RAM, GPR) in bytes.
-<p>For user program memory (variables, constants) the compiler allocates
-memory first in unshared RAM then in shared RAM.
-Some specific compiler 'internally' used bytes can be and should
-be allocated in shared RAM for optimum performance.
-<br>For the compiler 'shared' means: accessible in all banks.
-Memory which is accessible in more than one bank but not in all
-is declared as unshared RAM.
+<p>The device files specify the amounts of available data memory for
+variables in bytes.
+<p>There is a distinction between 'shared' and 'unshared' memory.
+For the compiler 'shared' means:
+<ul compact>
+<li>for baseline and midrange PICs: accessible in all banks
+regardless the value in STATUS_RP
+<li>for the extended midrange and 18F PICS: memory in the access bank
+</ul>
+Memory which is accessible in more than one bank but not in all banks
+is in this context 'unshared'.
+<p>The compiler allocates memory for regular ('user') variables in unshared
+memory.
+<p>The compiler needs some memory for internal use.
+These variables are named _pic_accum and _pic_isr_w,
+and <b>must</b> be allocated in shared memory.
+Each device files contains the declarations for these.
<p>Most PICS have both shared and unshared RAM and then there is no
-issue, but some PICs have only shared memory while some others have no
-shared memory at all.
-This complication is solved in the device files as follows:
+issue, neither is there an issue with PICs with only 1 memory bank.
+But some midrange PICs have only shared memory while some others have
+no shared memory at all.
+This complication is handled by the device files as follows:
<ul>
<li>For PICs with <b>only shared</b> memory all memory is declared as
-unshared, except for the compiler-required bytes.
-Examples: 12F675, 16F676, 16F873A.
-<li>For PICs with <b>only unshared</b> memory the compiler-required
-bytes are declared in unshared memory (upper address limit)
-Examples: 10Fs, 16f54, 16F74.
+unshared, except for the compiler-required variables.
+<br>Examples: 12F675, 16F676, 16F873A.
+<li>For PICs with <b>only unshared</b> memory the memory for the compiler
+required variables is declared 'shared' (even though it is in fact
+unshared memory!)
+and the locations with the same (7-bits) offset in other banks
+are reserved (excluded from the available data memory for user variables).
+<br>This is only partly a solution.
+It avoids problems with interrupt handlers (which use _pic_isr_w), but it
+does not completely avoid problems with calculations with multi-byte
+variables (which uses _pic_accum) when the variables are in different
banks.
+For the involved PICs a warning will be issued by the device files.
+<br>Examples: 16F73/74.
</ul>
-<p>The compiler supports a maximum of 4 memory banks for baseline and
-midrange PICs.
-When a PIC has more memory banks the device file declares only 4 of
-these, memory in the other banks is unusable.
-Example: 16F59.
-
-
<h3>Analog modules</h3>
<p>(to be done)
--
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.
