Revision: 1840
Author: robhamerling
Date: Fri Mar 26 06:31:12 2010
Log: Update of devicefiles.html, esp. the section about ANSEL normalisation.
http://code.google.com/p/jallib/source/detail?r=1840
Modified:
/trunk/doc/html/devicefiles.html
=======================================
--- /trunk/doc/html/devicefiles.html Thu Mar 4 13:12:28 2010
+++ /trunk/doc/html/devicefiles.html Fri Mar 26 06:31:12 2010
@@ -41,20 +41,16 @@
<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
-(such as the 16F690 and 12F683).
-The <b>Inc2Jal</b> utility to generate device definition files was designed
-for the original Jal compiler, was not updated for JalV2 and the device
-files it generated for my preferred PICs gave compile errors.
-Possible ways to resolve this issue might have been to update the generated
-device files manually or make Inc2Jal up-to-date for JalV2.
-I didn't like either of these (Inc2Jal is written in Pascal, which I hadn't
-used for many years).
-<br>Since I already had a Rexx script to scan MPlab files for my Xwisp2
-program I decided to take that route for a replacement of Inc2Jal.
-I named the new script <b>Dev2Jal</b> because it uses the .dev files of
-MPlab as base in stead of the .inc files like Inc2Jal.
+<p>The Jallib device files are generated by means of a Rexx
script 'dev2jal'.
+Its name as an abbreviation of 'MPlab-.dev to jal' because it uses the .dev
+files of the MPLAB-IDE to create the Jallib device files.
+<br>Notes:
+<ul>
+<li>The .lkr files of the MPASM component of MPLAB are used too!
+<li>Rexx is an interpreted language, see for example:
+http://www.rexxinfo.org/ and
+http://en.wikipedia.org/wiki/REXX
+</ul>
<p>The advantages of automated generation of device files are pretty
obvious, such as:
@@ -109,7 +105,7 @@
<p>The device files are the base for other include files and contain:
<ul>
<li>An include statement for the common include file 'chipdef_jallib'
-<li>CPU type specification (12-, 14- or 16-bits core).
+<li>CPU type specification (12-, 14-, extended 14-, or 16-bits core).
<li>Program memory size specification.
<li>Data memory (EEPROM) location and size specification.
<li>Configuration (fuses) and ID memory specification.
@@ -315,23 +311,23 @@
<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.
+<p>Because the upper and lower 4 bits ('nibble') of a port are
+used frequently as a unit, these are declared as pseudo variables.
<pre>
- PORTx_low - bits 0..3
- PORTx_high - bits 4..7
+ PORTx_low - bits 0..3 (low order bits)
+ PORTx_high - bits 4..7 (high order bits)
PORTx_low_direction
PORTx_high_direction
</pre>
This allows nibbles to be used as a regular variables,
-and also to set pin directions by 4 at a time:
+and can also be used to set pin directions by 4 at a time:
<pre>
- PORTA_high = "7" -- lower nibble remains unchanged
+ PORTA_high = "7" -- low nibble remains unchanged
PORTA_low_direction = all_output -- direction upper nibble unchanged
</pre>
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.
+nibble fully populated, or even not populated at all!
<h3>Alias names</h3>
@@ -537,44 +533,69 @@
<h3>Names of ANSEL bits</h3>
-<p>For the selection of the ADC channel the ADC library has to set the
-appropriate bit(s) of the ANSEL register(s), depending on the type of
-PIC.
-The baseline and midrange PICs have a couple of different ANSEL registers
-configurations.
-This would make it complicated to build a device independent ADC library.
-This is (partly) solved by declaring aliases for the channel selection
-bits in ANSEL registers.
-<br>The ANSx and ANSELx bits have a given prefix 'JANSEL' (a pseudo
-register name being a contraction of JALLIB-ANSEL).
-The name of the channel selection bit has the form AN<number>
-in which <number> counts from 0 to the maximum number,
-corresponding to the channel number in the datasheets.
-<br>As example below the declaration of ANS bit of the 16F886.
-This PIC has as ADC channels 0..4 and 8..13.
+<p>For the control of the ADC channel the ADC library has to set the
+appropriate pin(s) to analog (input).
+There are generally 3 methods used by the different PICs:
+<ul>
+<li>with the PCFG field of the ADCON1 register
+<li>with the PCFG bits in ANCONx registers
+<li>with bits of the ANSELx register(s)
+</ul>
+<p>The first two methods as covered by the ADC libraries,
+this section is about the third method with ANSEL register(s).
+There are a couple of issues with this method:
+<ul>
+<li>Pins with analog capability are not evenly and sequentially distributed
+over the ports.
+Sometimes channel numbers are not present and the numbering in the PORT
+register is sometimes 'chaotic'.
+<li>There is no direct relation between the number of the analog channel
+(pin_ANx, x in the range 0..28) and the bit in the ANSEL register with
which
+the channel is controlled.
+And the ANSEL registers are not uniformly named (e.g. the first register
can
+be ANSEL, ANSEL0, ANSELA, the second can be ANSELH, ANSEL1, ANSELB, etc.).
+</ul>
+<p>The first item is no problem when always referring to the logical pin
+name pin_ANx (an alias of the physical pin name).
+A solution for the second item has been found by declaring aliases for the
+channel selection bits in ANSEL registers (name normalization).
+In stead of enumerating the bits of all ANSELx registers individually, a
+number of bit aliases 'JANSEL_ANSx' is declared, in which 'x' represents
+the ADC channel and which point to the appropriate AN-pin.
+<br>For example the declaration of the JANSEL bits of a 16F722 looks like:
<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 ANSELA at { 0x185 }
+ var volatile bit JANSEL_ANS4 at ANSELA : 5 -- pin_AN4 =
pin_A5
+ var volatile bit JANSEL_ANS3 at ANSELA : 3 -- pin_AN3 =
pin_A3
+ var volatile bit JANSEL_ANS2 at ANSELA : 2 -- pin_AN2 =
pin_A2
+ var volatile bit JANSEL_ANS1 at ANSELA : 1 -- pin_AN1 =
pin_A1
+ var volatile bit JANSEL_ANS0 at ANSELA : 0 -- pin_AN0 =
pin_A0
-- -------------------------------------------------
- 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 ANSELB at { 0x186 }
+ var volatile bit JANSEL_ANS13 at ANSELB : 5 -- pin_AN13 =
pin_B5
+ var volatile bit JANSEL_ANS11 at ANSELB : 4 -- pin_AN11 =
pin_B4
+ var volatile bit JANSEL_ANS9 at ANSELB : 3 -- pin_AN9 =
pin_B3
+ var volatile bit JANSEL_ANS8 at ANSELB : 2 -- pin_AN8 =
pin_B2
+ var volatile bit JANSEL_ANS10 at ANSELB : 1 -- pin_AN10 =
pin_B1
+ var volatile bit JANSEL_ANS12 at ANSELB : 0 -- pin_AN12 =
pin_B0
</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
-a different register.
-The 16F724 and 16F727 have 21 ADC channels spread over 4 ANSELx
-registers, but these can controlled with the names JANSEL_ANS0 through
-JANSEL_ANS20.
-<p>Another example for the 10F222:
+As you can see the JANSEL_ANSx numbering is not restricted to bits 0..7
+of the first ANSEL register (whatever its name),
+it is also used for channel numbers higher than 7 controlled by another
+ANSEL register.
+Note further that:
+<ul>
+<li>channels 0..3 are regularly sequenced on pin_A0..3
+<li>channel 4 is on pin_A5 (pin_A4 is not an ADC pin)
+<li>channels 5..7 are missing
+<li>channels 8..13 are <b>ir</b>regularly sequenced on pin_B0..5
+</ul>
+<p>Other PICs, like for example the 18F43K22, have 28 ADC channels spread
+over 5 ANSEL registers, also largely irregularly numbered.
+For example pin_AN5..7 are controlled by ANSELE.
+The declaration of JANSEL_ANS0..27 hides all these irregularities from the
+ADC library.
+<p>Another example, now for the 10F222:
<pre>
var volatile byte ADCON0 at { 0x7 }
var volatile bit JANSEL_ANS1 at ADCON0 : 7
@@ -582,7 +603,7 @@
</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
-to know, because it uses the JANSEL alias.
+to know when it uses the JANSEL_ANSx alias.
<br><i>Note: in reality the channel selection of the 10F220/222 is
somewhat more complicated, but the ADC library takes care of that!</i>.
@@ -1400,24 +1421,24 @@
<p>The dev2jal script can be executed on other systems (Linux, Windows)
when a compatible Rexx interpreter is installed.
-'Regina Rexx' and the extension package 'Regutil' have proven to do fine
-for this script (tested under Windows XP).
-For more information about these free products see for example:
+The free 'Regina Rexx' has proven to do fine for this script
+(tested under Windows XP).
+For more information about Regina Rexx see:
<ul>
<li>http://regina-rexx.sourceforge.net/index.html
-<li>http://pages.interlog.com/~ptjm/regutil126.zip
</ul>
-<p>Download and install these packages when you want to run the script on a
-non-eComStation system.
+<p>Download and install the package (latest version 3.5) when you want to
+run the script on a non-eComStation system.
Probably the easiest way to run the script is:
<ul>
-<li>Copy /jallib/tools/dev2jal.cmd to the directory where you installed
Regina
-and RexxUtil (from the Regutil package).
+<li>Copy /jallib/tools/dev2jal.cmd to the directory where you installed
+Regina Rexx.
<li>Make the necessary changes in the script.
-<li>Start a CommandLine ('command prompt' / 'MS-DOS prompt' / 'terminal')
session
+<li>Start a CommandLine session ('command prompt' / 'MS-DOS prompt'
/ 'terminal').
<li>Go to the directory with Regina.
-<li>Type: regina dev2jal.cmd test
+<li>Enter the command: regina dev2jal test
</ul>
+The generated device files will be in subdirectory 'test' (./test).
</body>
</html>
--
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.
