Author: robhamerling
Date: Fri Mar 13 07:14:46 2009
New Revision: 845
Modified:
trunk/CHANGELOG
trunk/doc/html/devicefiles.html
Log:
extended and improved documentation file 'devicefile.html'
Modified: trunk/CHANGELOG
==============================================================================
--- trunk/CHANGELOG (original)
+++ trunk/CHANGELOG Fri Mar 13 07:14:46 2009
@@ -7,6 +7,7 @@
10 others, and name OSCCON_IRFC to OSCCON_IRCF for 16F88x group
- fixed NMMRs of 12-bits core: multi-bit bit fields now declared
as bit*<number> (was byte)
+ - extended and improved documentation file 'devicefiles.html'
externals:
- lcd_hd44780 refactured (API changes)
@@ -24,7 +25,7 @@
-
compiler:
- - version 2.4j
+ - replace by version 2.4j
jallib-0.2:
Modified: trunk/doc/html/devicefiles.html
==============================================================================
--- trunk/doc/html/devicefiles.html (original)
+++ trunk/doc/html/devicefiles.html Fri Mar 13 07:14:46 2009
@@ -1,10 +1,10 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
- <title>Device File Users Guide</title>
+ <title>Jallib Device Files Users Guide</title>
<meta http-equiv="content-type" content="text/html; charset=US-ASCII">
<meta name="author" content="Rob Hamerling">
- <meta name="description" content="Device File Users Guide">
+ <meta name="description" content="Jallib Device File Users Guide">
<meta name="copyright" content="Copyright (c) Rob Hamerling 2008..2009,
All rights reserved">
<meta name="project" content="This file is part of jallib
http://jallib.googlecode.com";>
<meta name="license" content="Released under the BSD license"
@@ -14,7 +14,7 @@
</head>
<body LANG="en-US" DIR="LTR">
-<h1>JalV2 Device Files</h1>
+<h1>Jallib Device Files Users Guide</h1>
<p><center>by Rob Hamerling</center>
<h2>Introduction</h2>
@@ -27,29 +27,28 @@
for JalV2.
I realized that more people would be in the same position like me.
Having some experience with scanning MPLAB files (for my Xwisp2 program)
-I decided to make script to generate the required include files, not only
-for the PICs for which I needed the include files, but for all PICs
-supported by the JalV2 compiler!
+I decided to make a script to generate the device files not only for the
+desired PICs, but for all PICs supported by the JalV2 compiler!
-<p> The advantages of using a script to generate files are obvious,
-such as:
+<p> The advantages of using a script to generate include files are
+pretty obvious, such as:
<ul>
<li>creation of device files for all PICmicros available in MPLAB
-<li>automatic update for new chips and corrections in new versions of
-MPLAB
+<li>automatic new device files for new chips in MPLAB
+<li>no manual maintenance
<li>consistent layout
<li>consistent naming convention
-<li>no typing errors
+<li>no errors due to typo's with manual editing
</ul>
-<p>The advantages of a standard naming convention are also obvious:
+<p>The advantages of a consistent naming convention are also obvious:
<ul>
<li>Easy migration of a program from one target PICmicro to another.
<li>Same for libraries using this naming convention.
</ul>
-<p>This document gives some design and user information about these JalV2
-device files.
+<p>This document gives some design information and user instruction
+about these JalV2 device files.
The sources of information are the xxxx.dev files and xxxx.lkr of MPLAB,
supplemented and corrected with information in the datasheets.
@@ -57,10 +56,6 @@
<h1>The Overall Picture</h1>
<p>With the design of the device files I had in mind a structure as shown
below.
-In the meantime these files have become part of the central JalV2 library
-repository <a href="http://jallib.googlecode.com/";>JalLib</a> at
-code.google.com.
-The Jallib structure is similar, but has its own standards.
<pre>
+----------+ +------------------+
| device | | general |
@@ -77,19 +72,24 @@
+----------+ +----------+ +----------+ +-------
</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 globally the same structure.
+
<h2>Device Files</h2>
-<p>This is the base for other include files and contains:
+<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>Program memory size specification.
<li>Data memory (EEPROM) location and size specification.
<li>Configuration (fuses) and ID memory specification.
+<li>Default fuse settings.
<li>Specification of General Purpose Register (GPR, RAM) location range and
sharing.
-<li>Declaation of Special Function Register (SFR) address and mirror
adresses,
+<li>Declaration of Special Function Register (SFR) address and mirror
adresses,
alias names and bit naming.
<li>Declaration of procedures and functions for shadowing of I/O ports.
<li>Declaration of symbolic names for configuration bits (fuses).
@@ -103,7 +103,7 @@
It is included by each of the device files and contains:
<ul>
<li>Constants required by the compiler.
-<li>Commonly used constants for the device files and other libraries.
+<li>Commonly used constants by the device files and other libraries.
</ul>
<p>With the statement 'pragma target chip = .....' in every device file the
@@ -130,21 +130,27 @@
target name and the corresponding value of target_chip is known by the
compiler.
-<p>Note: The original chipdef.jal file of the compiler package
-specifies different and not all values for 'target_chip' and therefore it
-has to be replaced when using this set of device files.
+<p>Note: The original chipdef.jal file of the compiler package specifies
+a different value for 'target_chip' and not for all PIC type.
+Therefore it has to be replaced when using this set of device files.
<h2>Function Include Files</h2>
-<p>Function specific include files can be included as required by the
-application program.
-In most cases these include files require some statements to couple
function
-specific registers and pins with the device.
-See the corresponding libraries and accompanying documentation for
-instructions.
-Frequently you can find user instructions as comments in the header of
-include files and just before the procedures and functions in these files.
+<p>Function specific include files offer facilities to ease the use of
+PIC peripherals (such as USART, ADC), external devices (such as LCDs,
+sensors), or extensions to the Jal language such as for data
+formatting, mathematical functions, etc.
+
+<p>Function specific include files should be included explicitly as
+required by the application program, this is not done by the device files.
+
+<p>In most cases the function include files require some statements to
+couple function specific registers and pins with the device.
+Read the comments in the library sources and the library documentation
+for instructions.
+Most libraries contain comments with user instructions in the header of
+include files and just ahead of the procedures and functions in these
files.
@@ -156,17 +162,19 @@
<p>The device files define static device (PICmicro) specific matter.
This allows writing elementary programs, such as for a blinking LED, which
-become practically device independent.
+are almost device independent
+(differences are mostly in the fuse settings).
<p>The device files are also the base for extensions, such as
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
-PIC16F886 using a 20 MHz resonator. In addition to the device-specific
-information obtained from the include file '16f886.jal' some run-time
-iformation is needed, like the speed and type of the oscillator and some
-other 'environmental' variables. No extra function libraries are required.
+PIC16F886 using a 20 MHz resonator.
+In addition to the device-specific information obtained from the include
+file '16f886.jal' some run-time iformation is needed, like the speed and
+type of the oscillator and some other 'environmental' variables.
+No extra function libraries are required.
<pre>
-- ------ Blink-an-LED on pin A1 of a PIC16F886 --------
@@ -259,8 +267,8 @@
<p>Notes:
<ol>
-<li>When you have used Jal before you may notice some differences in naming
-convention:
+<li>When you have used Jal before with other device files or libraries
+ you may notice some differences in naming convention:
<ul>
<li>PORTA is used consistently, while previously PORT_A was a
popular naming convention especially for PORT_A_low/high,
@@ -270,9 +278,10 @@
<br>var volatile bit INTCON_GIE at INTCON : 7
</ul>
<li>See the extra alias declarations for the GPIO and TRISIO registers
- and their bits. Programs and function libraries can access the
- GPIO bits with PORTA and pin_Ay names, making it possible to
- use libraries across a large collection of PICmicros.
+ and their bits.
+ Programs and function libraries can access the GPIO bits with PORTA
+ and pin_Ay names, making it possible to use libraries across a large
+ collection of PICmicros.
</ol>
<h3>MSSP modules</h3>
@@ -309,7 +318,7 @@
<h2>Special Features</h2>
<p>The device files contain a number of special procedures for the
-convenience of a JAL programmer.
+convenience of the JAL programmer.
Most procedures are in the form of a pseudo variable, some are 'normal'
procedures.
Pseudo variables a available for TRISA, TRISB and TRISC and corresponding
@@ -324,14 +333,24 @@
<p>Port shadowing is a technique to prevent the Read-Modify-Write problem
with I/O ports of PICmicro's.
-This is a problem related to its hardware design and may occur when a read
-of a port is immediately followed by writing to that port.
-With port shadowing a RAM location is used as replacement for the port.
-Reading is done from the port directly.
-Writing is done to the shadow register and then its contents flushed to the
+This is a problem related to its hardware design.
+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
+the Jallib device files you won't face the problem when you follow some
+simple rules and a avoid a few pitfalls.
+
+<p>With port shadowing for the baseline and midrange PICs
+(10F, 12F, 16F) a RAM location is used as replacement for the port for
+output.
+The 18F series have a special register for this purpose (LATx).
+Although the techniques are slightly different, the general rules are:
+reading is done from the port directly, while writing is done to the
+shadow register of which the contents is subsequently passed to the
real port.
-<p>With these device files shadowing is automatic, as long
+<p>With the Jallib device files shadowing is automatic, as long
as you use the following names:
<pre>
PORTx - all bits of port x
@@ -340,18 +359,24 @@
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
+reading from (and must be passed with writing to) in the lower nibble
+(bits 3..0) of a constant or variable.
+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.
-<p>If you want to use other names for pins or nibbles or the whole port you
-can specify an alias.
+<p>If you want to use other names for ports, nibbles or individual pins
+you must specify an alias.
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.
-<p>You should avoid direct pin and I/O port manipulation, because it will
be
-overruled by the automatic shadowing mechanism. For example do not specify:
+<p>You should <b>avoid direct pin and I/O port manipulation</b>, because
+it will be overruled by the automatic shadowing mechanism. For example
+do <b>not</b> specify:
<pre>
var bit led_red at portA : 0
</pre>
@@ -378,13 +403,13 @@
<li>For all implemented configuration bits an option name and two or more
tags are defined, but the chosen names may not always be intuitive or
convenient.
-Some are very long!
+Some names or tags are very long!
<li>When the compiler stalls over a fuse-def line a correction should
be applied.
-If you encounter such occasion please reports such cases in the Jallib
group
-at Google Groups or Jallist at Yahoo! groups.
-<li>For the most popular configuration bits a 'standard' option name is
-defined, along with a 'standard' tag, see the list below.
+If you encounter such 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
@@ -515,9 +540,10 @@
pragma target fuses 0b11_0011_1110_0010
</pre>
-<p>PICs with 16-bits core (the 18F series) have such a large variety of
-configuration bits that explicit specification is probably the best way to
-make sure all configuration bits are set correctly for your program.
+<p>PICs with 16-bits core (the 18F series) have such a large set and
+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
with an 18F242.
<pre>
@@ -543,8 +569,10 @@
the device file.
<li>When a PIC has multiple configuration words or bytes the index value
of the word or byte must be specified before the value.
-<li>The device file contains a fuses specification for the compiler:
+<li>The device file contains a fuses specification:
how many words/bytes and their corresponding memory addresses.
+Also a default fuse setting is specified, which may or may not be
+suitable for your application!
</ol>
<p>The meaning of configuration bits can in most cases be found in the
@@ -579,8 +607,8 @@
.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
-from this source are not guaranteed errorfree too!
+Apart from that, MPLAB is not errorfree, consequently include files
generated
+from this source cannot be guaranteed to be errorfree either!
<li>The naming convention of ports and subfields maybe different, you may
have to convert the other libraries.
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
