Author: robhamerling
Date: Sat Apr 4 02:40:31 2009
New Revision: 912
Modified:
trunk/doc/html/devicefiles.html
trunk/include/external/lcd/lcd_hd44780_4.jal
trunk/include/external/lcd/lcd_hd44780_8.jal
trunk/include/external/lcd/lcd_hd44780_common.jal
trunk/include/peripheral/usart/serial_hw_int_cts.jal
Log:
Devicefiles.html: fixed typos, some textual enhancements
Libraries: changed comments for better html output (Jalapi)
Modified: trunk/doc/html/devicefiles.html
==============================================================================
--- trunk/doc/html/devicefiles.html (original)
+++ trunk/doc/html/devicefiles.html Sat Apr 4 02:40:31 2009
@@ -162,8 +162,8 @@
<p>The device files define static device (PICmicro) specific matter.
This allows writing elementary programs, such as for a blinking LED, which
-are almost device independent
-(differences are mostly in the fuse settings).
+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
@@ -172,7 +172,7 @@
<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
+file '16f886.jal' some run-time information is needed, like the speed and
type of the oscillator and some other 'environmental' variables.
No extra function libraries are required.
@@ -214,18 +214,29 @@
<p>Unfortunately MPLAB of Microchip is not particularly consistent in its
choice of names!
-The datasheets and various informational files in MPLAB not infrequently
use
-different names for the same entity!
-Since application programmers are supposed to read the datasheets, the most
-obvious would be to use the datasheet names, but these are not part of
MPLAB
-and would have to be downloaded separately.
-And these PDF files are not so easily processed with a script.
-So the chosen names are possibly not to what you may be familiar with.
+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.
+However the device files have been generated from the MPLAB information
+files, not the datasheets!
+Therefore it is possible that some names may not be conform the datasheet.
+When you find such a deviation, please report to the Jallib team!
<p>For all registers of the chip a name is defined and where appropriate
-also the individual bits or groups of bis are declared.
-Also some popular aliases for registers are defined, for example: TMR0IF
and
-T0IF, TMR0IE and T0IE, etc.
+also the individual bits or groups of bits are declared.
+Also some aliases are declared for easy the migration or conversion of
+existing JalV2 libraries and programs to the Jallib environment.
+
+<p>There are also exceptions to the rules above.
+For example the interrupt bits of Timer 0 are declared as TMR0IE and
+TMR0IF for <b>all</b> devices, even though some datasheets use the names
+T0IE and T0IF.
+This is just an example, see below for more.
+<br>This 'normalization' is done to be able to use all libraries for all
+types of PICmicros.
+As side-effect also programs can be migrated to other types of PICs more
+easily.
+
<h3>PORTx and TRISx</h3>
<p>For all ports and port pins a device independent alias is defined and a
@@ -259,42 +270,41 @@
<p>etc. (for all other existing pins)
<h3>Non-memory-mapped registers</h3>
-<p>Some PICs, especially in the baseline series, are missing some memory
-mapped registers.
-For example the 12-bit core (10Fs, 12F5x, etc) have no memory mapped
-TRISx registers, in stead these PICs have TRISx instructions to set
-the direction of ports or pins.
-This would make it impossible for application programs or function
-libraries to use statements like:
+<p>Some PICs, especially in the baseline series, are missing some
+addressable ('memory mapped') registers.
+For example the 12-bit core PICs (10Fs, 12F5x, etc) have no memory
+mapped TRISx registers, in stead these PICs have TRISx instructions to
+set the direction of ports or pins.
+This would make it impossible for function libraries and application
+programs to use statements like:
<pre>
PORTA_direction = all_output
</pre>
-<p>For this reason the device files contain pseudo variables which mimic
-the existence of memory mapped registers.
-This makes it possible to use statement like the one above.
+<p>The device files contain pseudo variables which mimic the existence
+of memory mapped registers,
+and now you can use statements like the one above.
<p>For example: even though a 16F59 has no addressable TRISC register,
-you can still use
+you can still specify:
<pre>
pin_C5_direction = output
</pre>
-<p>
<h3>Nibbles</h3>
<p>Since frequently the upper and lower 4 bits ('nibble') of a port are
-used as a unit, some procedures and functions are defined to use port
-nibbles as a regular variable and set pin directions by 4:
+used as a unit, these are defined as pseudo variables.
<pre>
PORTx_low - bits 0..3
PORTx_high - bits 4..7
PORTx_low_direction
PORTx_high_direction
</pre>
-<p>This makes it possible to use statements like:
+<p>This allows nibbles to be used as a regular variables,
+and also to set pin directions by 4 at a time:
<pre>
- PORTA_low_direction = all_output
- PORTA_low = "7" -- upper nibble remains unchanged
+ PORTA_high = "7" -- lower nibble remains unchanged
+ PORTA_low_direction = all_output -- direction upper nibble unchanged
</pre>
-<p>Several Jallib function libraries use this facility.
+<p>Several function libraries in the Jallib collection use this facility.
<h3>Names of MSSP modules</h3>
<p>Names of registers of MSSP modules have been normalized as follows:
@@ -342,15 +352,15 @@
<h2>About Port Shadowing</h2>
-<p>Port shadowing is a technique to prevent the Read-Modify-Write problem
-with I/O ports of PICmicro's.
+<p>Port shadowing is a technique to prevent the Read-Modify-Write
+('RMW') problem with I/O ports of PICmicro's.
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!
+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.
+simple rules and 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
Modified: trunk/include/external/lcd/lcd_hd44780_4.jal
==============================================================================
--- trunk/include/external/lcd/lcd_hd44780_4.jal (original)
+++ trunk/include/external/lcd/lcd_hd44780_4.jal Sat Apr 4 02:40:31 2009
@@ -11,7 +11,7 @@
--
-- Description:
-- Nibble interface for HD44780 compatible alphanumeric LCD screens.
---
+-- .
-- Expects: - 2 pins for handshake: 'lcd_rs' and 'lcd_en'
-- and
-- - 1 port nibble for data: 'lcd_dataport'
@@ -19,7 +19,7 @@
-- - 4 lines for data: 'lcd_d4' .. 'lcd_d7'
-- note: a 'port nibble' - the lower or higher 4 bits of a port -
give
-- faster and more compact code then random selected data
lines.
--- --
+-- .
-- Directions for use of this library in application programs
-- (in this sequence):
-- 1. Declare the following constants:
@@ -35,7 +35,7 @@
-- var bit lcd_d5 is pin_A1 -- databit d5 pin
-- var bit lcd_d6 is pin_C0 -- databit d6 pin
-- var bit lcd_d7 is pin_C2 -- databit d7 pin
--- --
+-- .
-- 2. Set the chosen LCD dataport and handshake pins to output:
-- pin_A4_direction = output
-- pin_A5_direction = output
@@ -46,24 +46,25 @@
-- pin_A1_direction = output -- set data pin as
output
-- pin_C0_direction = output -- set data pin as
output
-- pin_C2_direction = output -- set data pin as
output
--- --
+-- .
-- 3. Include this library.
--- --
+-- .
-- 4. Call lcd_init() to initialize the lcd controller.
--- --
--- Above is an example for a 2x16 LCD:
--- --
+-- .
+-- Above is an example for a 2x16 LCD.
+-- .
-- See hd_44780_common for the LCD API.
--
-- Dependencies: delay.jal
+-- lcd_hd44780_common.jal
--
--
-----------------------------------------------------------------------------
include delay
--
----------------------------------------------------------------------------
--- sends low nibble from value to the LCD
--- can be used for both commands and data
+-- Sends low nibble in <value> to LCD
+-- Can be used for both commands and data
-- (requires no wait cycli inbetween upper and lower nibble)
-- (this routine is only used inside this file)
--
----------------------------------------------------------------------------
@@ -72,19 +73,19 @@
if (defined(lcd_dataport) == TRUE) then
-- write nibble at once
- lcd_dataport = value -- replace low nibble
+ lcd_dataport = value -- replace low nibble
else
-- write nibble bit by bit
- var bit bit0 at value : 0
- var bit bit1 at value : 1
- var bit bit2 at value : 2
- var bit bit3 at value : 3
-
- -- setup databits
- lcd_d4 = bit0
- lcd_d5 = bit1
- lcd_d6 = bit2
- lcd_d7 = bit3
+ var bit bit0 at value : 0
+ var bit bit1 at value : 1
+ var bit bit2 at value : 2
+ var bit bit3 at value : 3
+
+ -- setup databits
+ lcd_d4 = bit0
+ lcd_d5 = bit1
+ lcd_d6 = bit2
+ lcd_d7 = bit3
end if
-- generate clockpuls
@@ -93,52 +94,44 @@
lcd_en = LOW -- trigger off
end procedure
---
----------------------------------------------------------------------------
--
----------------------------------------------------------------------------
--- sends byte from value to register of the LCD
--- (this procedure is only used inside this file)
---
+-- Sends byte in <value> to LCD
+-- (this procedure is only used inside this library)
--
----------------------------------------------------------------------------
procedure __lcd_write( byte in value ) is
__lcd_write_nibble(value >> 4) -- write high nibble
__lcd_write_nibble(value) -- write low nibble
delay_10us(4) -- > 37 us
end procedure
---
----------------------------------------------------------------------------
--
----------------------------------------------------------------------------
--- sends data byte in value to LCD
--- for slow commands an extra delay should be added
---
+-- Sends data byte in <value> to LCD
--
----------------------------------------------------------------------------
procedure _lcd_write_data(byte in value) is
lcd_rs = high -- select instruction
__lcd_write( value ) -- output byte
end procedure
---
----------------------------------------------------------------------------
--
----------------------------------------------------------------------------
--- sends command byte in value to LCD
--- for slow commands an extra delay should be added
---
+-- Sends command byte in <value> to LCD
+-- For slow commands an extra delay should be added
--
----------------------------------------------------------------------------
procedure _lcd_write_command(byte in value) is
; pragma inline
lcd_rs = low -- select instruction
__lcd_write( value ) -- output byte
end procedure
---
----------------------------------------------------------------------------
-- now we defined the interface, add the API
include lcd_hd44780_common
--
----------------------------------------------------------------------------
---
----------------------------------------------------------------------------
+-- Initialize LCD controller to 4-bit mode
--
----------------------------------------------------------------------------
procedure lcd_init() is
Modified: trunk/include/external/lcd/lcd_hd44780_8.jal
==============================================================================
--- trunk/include/external/lcd/lcd_hd44780_8.jal (original)
+++ trunk/include/external/lcd/lcd_hd44780_8.jal Sat Apr 4 02:40:31 2009
@@ -19,7 +19,7 @@
-- - 8 lines for data: 'lcd_d0' .. 'lcd_d7'
-- note: a 'port nibble' - the lower or higher 4 bits of a port -
give
-- faster and more compact code then random selected data
lines.
--- --
+-- .
-- Directions for use of this library in application programs
-- (in this sequence):
-- 1. Declare the following constants:
@@ -42,7 +42,7 @@
-- var bit lcd_d5 is pin_B1 -- databit d5 pin
-- var bit lcd_d6 is pin_C0 -- databit d6 pin
-- var bit lcd_d7 is pin_C2 -- databit d7 pin
--- --
+-- .
-- 2. Set the chosen LCD handshake pins to output:
-- pin_D2_direction = output
-- pin_D3_direction = output
@@ -60,26 +60,27 @@
-- pin_B1_direction = output -- set data pin as output
-- pin_C0_direction = output -- set data pin as output
-- pin_C2_direction = output -- set data pin as output
--- --
+-- .
-- 3. Include this library.
--- --
+-- .
-- 4. Call lcd_init() to initialize the lcd controller.
--- --
+-- .
-- Above is an example for a 2x16 LCD.
--- --
+-- .
-- See hd_44780_common for the LCD API.
--
--- Dependencies: delay.jal
+-- Dependencies:
+-- delay.jal
+-- lcd_hd44780_common.jal
--
--
-----------------------------------------------------------------------------
---
+
include delay
--
----------------------------------------------------------------------------
--- sends byte from value to register of the LCD
--- (this procedure is only used inside this file)
---
+-- Sends byte in <value> to the LCD
+-- (this procedure is only used inside this file).
--
----------------------------------------------------------------------------
procedure __lcd_write( byte in value ) is
if (defined(lcd_dataport) == TRUE) then
@@ -113,39 +114,34 @@
lcd_en = LOW -- trigger off
delay_10us(4) -- > 37 us
end procedure
---
----------------------------------------------------------------------------
--
----------------------------------------------------------------------------
--- sends data byte in value to LCD
--- for slow commands an extra delay should be added
---
+-- Sends data byte in <value> to LCD
--
----------------------------------------------------------------------------
procedure _lcd_write_data(byte in value) is
lcd_rs = high -- select instruction
__lcd_write( value ) -- output byte
end procedure
---
----------------------------------------------------------------------------
--
----------------------------------------------------------------------------
--- sends command byte in value to LCD
--- for slow commands an extra delay should be added
---
+-- Sends command byte in <value> to LCD
+-- For slow commands an extra delay should be added
--
----------------------------------------------------------------------------
procedure _lcd_write_command(byte in value) is
; pragma inline
lcd_rs = low -- select instruction
__lcd_write( value ) -- output byte
end procedure
---
----------------------------------------------------------------------------
-- now we defined the interface, add the API
include lcd_hd44780_common
+
--
----------------------------------------------------------------------------
---
----------------------------------------------------------------------------
+-- Initialise the LCD controller and API
--
----------------------------------------------------------------------------
procedure lcd_init() is
@@ -165,3 +161,4 @@
_hd44780_init()
end procedure
+
Modified: trunk/include/external/lcd/lcd_hd44780_common.jal
==============================================================================
--- trunk/include/external/lcd/lcd_hd44780_common.jal (original)
+++ trunk/include/external/lcd/lcd_hd44780_common.jal Sat Apr 4 02:40:31
2009
@@ -1,5 +1,5 @@
--
-------------------------------------------------------------------------
--- Title: common for HD44780 based LCD
+-- Title: common library for HD44780 based LCD
--
-- Author: Richard Zengerink, Copyright (c) 2008..2009, all rights
reserved.
--
@@ -11,65 +11,64 @@
-- Released under the BSD license
(http://www.opensource.org/licenses/bsd-license.php)
--
-- Description: Common API for HD44780 based LCD
---
-------------------------------------------------------------------------
--- procedures which can be used in your Main file:
---
-------------------------------------------------------------------------
--- ---------------
+-- .
+-- Procedures which can be used by application program:
+-- .
-- * lcd_write_char( byte in value ):
-- writes 'value' to lcd
-- example: lcd_write_char( "E" ) or lcd_write_char( 69 )
--- ---------------
+-- .
-- * lcd = value:
-- writes 'value' to lcd
--- example: lcd = "E" or lcd = 69
--- ---------------
+-- example: lcd = "E" or lcd = 69
+-- .
-- * lcd_cursor_position(byte in line, byte in pos):
-- places the cursor on position (pos) in line (line) (zero based!)
-- example: lcd_new_line_cursor_position (1, 8)
--- --------------
+-- .
-- * lcd_shift_left(byte in value):
-- shifts the display [value] times to the left without changing DDRAM
data.
-- example: lcd_shift_left(4)
-- or lcd_shift_left(variable)
--- --------------
+-- .
-- * lcd_shift_right(byte in value):
-- shifts the display [value] times to the right without changing DDRAM
data.
-- example: lcd_shift_right(12)
-- or lcd_shift_right(variable)
--- --------------
+-- .
-- * lcd_cursor_shift_left(byte in value):
-- shifts the cursor [value] times to the left without changing display
-- contents and DDRAM data.
-- example: lcd_cursor_shift_left(8)
-- or lcd_cursor_shift_left(variable)
--- --------------
+-- .
-- * lcd_cursor_shift_right(byte in value):
-- shifts the cursor [value] times to the right without changing display
-- contents and DDRAM data.
-- example: lcd_cursor_shift_right(3)
-- or lcd_cursor_shift_right(variable)
--- --------------
--- * lcd_clear:
+-- .
+-- * lcd_clear:
-- Write "20H" to DDRAM and set DDRAM address to "00H" from AC
-- This will clear the display.
--- --------------
+-- .
-- * lcd_home:
-- Set DDRAM address to "00H" from AC and return cursor to its original
-- position if shifted. The contents of DDRAM are not changed.
--- --------------
+-- .
-- * lcd_cursor_blink_display(bit in cursor,bit in blink,bit in display):
-- sets the underline cursor on/off, let the block-cursor blinking/off
-- and puts the display on/off
-- example: lcd_cursor_blink_display(on,off,on)
--- --------------
+-- .
-- * lcd_clear_line ( byte in line )
-- clears the line [line] of the lcd including DDRAM data of that line
-- example: lcd_clear_line(1)
--- --------------
+-- .
-- * lcd_progress(byte in line, byte in amount)
-- create a progress bar on line [line] with a lenght of [amout]
-- example: lcd_progress(2,12)
--- --------------
+--
--
-- Sources:
--
@@ -90,60 +89,56 @@
const LCD_SET_DDRAM_ADDRESS = 0b_1000_0000
--
----------------------------------------------------------------------------
-var volatile byte lcd_pos = 0
+var volatile byte lcd_pos = 0
---
----------------------------------------------------------------------------
--- _lcd_line2index - internal function - calculate index from line number
--
----------------------------------------------------------------------------
+-- _lcd_line2index - internal function - calculate index from line number
--
----------------------------------------------------------------------------
function _lcd_line2index(byte in line) return byte is
- -- force valid line number
+ -- force valid line number
if (line >= LCD_ROWS) then line = 0 end if
- case line of
+ case line of
0: return 0x00
1: return 0x40
2: return 0x00 + LCD_CHARS
3: return 0x40 + LCD_CHARS
- end case
-
-end function
---
----------------------------------------------------------------------------
+ end case
+
+end function
+
--
----------------------------------------------------------------------------
-- _lcd_restore_cursor - sets the cursor to the position in the shadow
register
---
----------------------------------------------------------------------------
-- (this routine is only used inside this file)
--
----------------------------------------------------------------------------
procedure _lcd_restore_cursor() is
-- set LCD back to normal operation
_lcd_write_command( lcd_set_ddram_address | lcd_pos )
end procedure
---
----------------------------------------------------------------------------
+
--
----------------------------------------------------------------------------
-- lcd_write_char - write one char to LCD
--
----------------------------------------------------------------------------
---
----------------------------------------------------------------------------
procedure lcd_write_char(byte in data) is
_lcd_write_data(data)
-end procedure
---
----------------------------------------------------------------------------
+end procedure
+
--
----------------------------------------------------------------------------
-- lcd'put - write one char to screen (pseudo var, enables streams)
--
----------------------------------------------------------------------------
---
----------------------------------------------------------------------------
procedure lcd'put(byte in data) is
; pragma inline -- disabled due to complier bug with inline +
pseudovar/arrays.
_lcd_write_data(data)
-end procedure
---
----------------------------------------------------------------------------
+end procedure
+
--
----------------------------------------------------------------------------
-- lcd_cursor_position - Specify row and column (0-based)
---
----------------------------------------------------------------------------
+-- .
-- About cursor positions: the LCDs are internally 2x40 char devices.
-- The first line starts at offset 0, the second line at offset 64 (0x40).
-- With 4 line devices the third and fourth line are addressed as
extensions
@@ -159,20 +154,20 @@
lcd_pos = pos + _lcd_line2index(line)
_lcd_restore_cursor()
end procedure
---
----------------------------------------------------------------------------
+
--
----------------------------------------------------------------------------
-- lcd_shift_left - shifts the complete display one position to the left
--
----------------------------------------------------------------------------
procedure lcd_shift_left(byte in nr) is
- -- set LCD back to normal operation
+ -- set LCD back to normal operation
if nr != 0 then
for nr loop
_lcd_write_command(LCD_DISPLAY_SHIFT_LEFT)
end loop
end if
end procedure
---
----------------------------------------------------------------------------
+
--
----------------------------------------------------------------------------
-- lcd_shift_right - shifts the complete display one position to the right
@@ -184,7 +179,7 @@
end loop
end if
end procedure
---
----------------------------------------------------------------------------
+
--
----------------------------------------------------------------------------
-- lcd_cursor_shift_left - shifts cursor one position to the left
@@ -196,7 +191,7 @@
end loop
end if
end procedure
---
----------------------------------------------------------------------------
+
--
----------------------------------------------------------------------------
-- lcd_cursor_shift_right - shifts cursor one position to the right
@@ -208,7 +203,6 @@
end loop
end if
end procedure
---
----------------------------------------------------------------------------
--
----------------------------------------------------------------------------
@@ -218,11 +212,11 @@
_lcd_write_command(LCD_CLEAR_DISPLAY)
delay_10us( 180 )
end procedure
---
----------------------------------------------------------------------------
+
--
----------------------------------------------------------------------------
--- lcd_cursor_blink_display - (re)sets cursor blink and puts display on/off
---
----------------------------------------------------------------------------
+-- lcd_cursor_blink_display - (re)sets cursor blink and puts display on/off
+-- .
-- params:
-- cursor: enable or disable the fixed underline cursor
-- blink: enable or disable blinking of the block-cursor (so block
blinking or off)
@@ -237,7 +231,7 @@
if blink then reg = reg + 1 end if
_lcd_write_command( reg )
end procedure
---
----------------------------------------------------------------------------
+
--
----------------------------------------------------------------------------
-- lcd_home - cursor returns home(line 0, position 0)
@@ -246,7 +240,7 @@
_lcd_write_command(LCD_RETURN_HOME)
delay_10us( 180 )
end procedure
---
----------------------------------------------------------------------------
+
--
----------------------------------------------------------------------------
-- lcd_clear_line - clears the line "line" of the LCD
@@ -254,28 +248,28 @@
procedure lcd_clear_line(byte in line) is
-- set LCD-cursor at start of line
lcd_pos = _lcd_line2index(line)
-
+
_lcd_restore_cursor()
-- now fill line with spaces
for LCD_CHARS loop
lcd = " "
end loop
-
+
-- set LCD back to normal operation
_lcd_restore_cursor()
-
+
end procedure
---
----------------------------------------------------------------------------
+
--
----------------------------------------------------------------------------
-- lcd_progress- Displays a progress bar
---
----------------------------------------------------------------------------
+--
----------------------------------------------------------------------------
-- The progress bar starts at position 0 of a line.
--
-- line: line on which progress bar is displayed
--- amount: number of bar chars that are displayed
---
+-- amount: number of bar chars that are displayed
+--
-- (0xFF is a common pattern)
--
----------------------------------------------------------------------------
procedure lcd_progress(byte in line, byte in amount, byte in pattern) is
@@ -293,11 +287,12 @@
end procedure
+
--
----------------------------------------------------------------------------
-- _hd44780_init - Initialise display (not realy internal, but not for
users)
---
----------------------------------------------------------------------------
+--
-- This procedure is called from lcd_init of the interface used. lcd_init
brings
--- up the interface and powers up the display.
+-- up the interface and powers up the display.
-- This procedure sets the display in the pre-defined startposition (clear
-- screen, no cursor etc).
--
----------------------------------------------------------------------------
@@ -311,16 +306,17 @@
end procedure
-
--- deprecated procedures
+--
----------------------------------------------------------------------------
+-- Deprecated
procedure lcd_clearscreen() is
_warn "lcd_clearsceen() is deprecated - please use lcd_clear_screen()"
_lcd_write_command( lcd_clear_display )
delay_10us( 180 )
end procedure
-
+
+-- Deprecated
procedure lcd_writechar(byte in data) is
_warn "lcd_writechar() is deprecated - please use lcd_write_char()"
_lcd_write_data(data)
-end procedure
-
\ No newline at end of file
+end procedure
+
Modified: trunk/include/peripheral/usart/serial_hw_int_cts.jal
==============================================================================
--- trunk/include/peripheral/usart/serial_hw_int_cts.jal (original)
+++ trunk/include/peripheral/usart/serial_hw_int_cts.jal Sat Apr 4
02:40:31 2009
@@ -1,49 +1,47 @@
-- ----------------------------------------------------------------------
-- Title: serial_hw_int_cts.jal. Interrupt driven buffered serial
interface with flow control.
--- Author: Rob Hamerling, Copyright (c) 2008..2008, all rights reserved.
+-- Author: Rob Hamerling, Copyright (c) 2008..2009, all rights reserved.
-- Adapted-by: Joep Suijs
-- Compiler: =2.4h
--
-- This file is part of jallib (http://jallib.googlecode.com)
-- Released under the ZLIB license
(http://www.opensource.org/licenses/zlib-license.html)
--
--- Description: Serial communications
--- - receive and transmit data transfer is interrupt driven
--- - receive and transmit data transfer uses circular buffers
--- - automatic CTS flow control with spare free space for
FiFo buffer
---
--- Sources:
---
--- Notes:
+-- Description:
+-- Serial communications:
+-- - receive and transmit data transfer is interrupt driven
+-- - receive and transmit data transfer uses circular buffers
+-- - automatic CTS flow control with spare free space for FiFo buffer
--
-- This library supports:
--- - Data format: 8 bits data, 1 start-bit, 1 stop bit
--- - Fixed speed in the range 1200..57600, depending on the resonator
--- frequency (see BAUD RATES tables in the datasheet with BRGH=1).
--- - Interrupt bits TXIE, RCIE, PEIE and GIE
+-- - Data format: 8 bits data, 1 start-bit, 1 stop bit
+-- - Acceptable baud rate depends on the resonator frequency
+-- (see BAUD RATES tables in the datasheet with BRGH=1).
+-- - Interrupt bits used: TXIE, RCIE, PEIE and GIE.
--
-- Available procedures/functions for application programs:
--
--- - serial_setup() -- initialise
communications
--- -- (called automatically)
--- - serial_send_byte(byte out <byte>) -- send byte
--- -- returns the transmitted
byte
--- - serial_hw_read(byte out <byte>) return bit -- receive byte
--- -- returns TRUE with data,
--- -- FALSE when no data
available
--- - serial_hw_write(byte in <byte>) -- send byte (wait if
queue full)
--- --
--- - serial_hw_data = <byte> -- send byte, wait if
queue full
--- - <byte> = serial_hw_data -- receive byte, wait if
queue empty
--- -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+-- - serial_setup() -- initialise
communications
+-- -- (called automatically)
+-- - serial_send_byte(byte out <byte>) -- send byte
+-- -- returns the
transmitted byte
+-- - serial_hw_read(byte out <byte>) return bit -- receive byte
+-- -- returns TRUE with data,
+-- -- FALSE when no data
available
+-- - serial_hw_write(byte in <byte>) -- send byte (wait if
queue full)
+--
+-- - serial_hw_data = <byte> -- send byte, wait if
queue full
+--
+-- - <byte> = serial_hw_data -- receive byte, wait if
queue empty
+--
--
-- Directions for use of this library in application programs
-- (in this sequence):
--
-- 1. Declare the following constant:
--
--- const serial_hw_baudrate = 19200 -- host communications
--- -- (range 9600..57600)
+-- const serial_hw_baudrate = 19200 -- line speed
+--
-- and variables:
--
-- var bit serial_ctsinv is pin_B4 -- incoming data flow
control
@@ -55,7 +53,7 @@
-- -- without notification,
but
-- -- this is prevented with
CTS.
--
--- and optional, you could define one or more of the constants below.
+-- and optional, you could define one or more of the constants below.
-- You should do so if you want different value's then the ones shown.
-- If any of these constants is not defined, the value shown is used:
--
@@ -74,20 +72,6 @@
--
-- 4. Call serial_init() to initialize serial communications.
--
--- Notes: - For data transmit and receive the pins TX and RX are used
--- automatically, these have not to be assigned by the
application.
--- - The selection of the CTS pin above is an example, any other pin
--- which is configurable for output can be used.
--- - When CTS flow control is not desired then assign serial_ctsinv
--- to a dummy bit, for example:
--- var bit dummy_cts_bit
--- var bit serial_ctsinv is dummy_cts_bit
--- - The serial_overflow_discard flag may be dynamically changed
--- (depending on how important the data is for the receiving
party).
--- - Do not touch the following interrupt bits: TXIE, RCIE, PEIE
and GIE
---
--- -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
---
-- Some background information:
--
-- The PIC ports use positive logic: '1' is positive voltage, '0' is
ground.
@@ -115,27 +99,43 @@
-- Remember also: RxD of RS232-plug connects to TX of PIC via MAX2x2
-- TxD of RS232-plug connects to RX of PIC via MAX2x2
--
+-- Sources:
+--
+-- Notes:
+-- - For data transmit and receive the pins TX and RX are used
+-- automatically, these have not to be assigned by the application.
+-- - The selection of the CTS pin above is an example, any other pin
+-- which is configurable for output can be used.
+-- - When CTS flow control is not desired then assign serial_ctsinv
+-- to a dummy bit, for example:
+-- var bit dummy_cts_bit
+-- var bit serial_ctsinv is dummy_cts_bit
+-- - The serial_overflow_discard flag may be dynamically changed
+-- (depending on how important the data is for the receiving party).
+-- - Do not touch the following interrupt bits: TXIE, RCIE, PEIE and GIE
+--
+--
-- ----------------------------------------------------------------------
--
-- setup defaults if no value is specified
--
if (defined(SERIAL_XMTBUFSIZE) == false) then
- const SERIAL_XMTBUFSIZE = 32 -- default size of transmit
buffer
+ const SERIAL_XMTBUFSIZE = 32 -- default size of
transmit buffer
end if
if (defined(SERIAL_RCVBUFSIZE) == false) then
- const SERIAL_RCVBUFSIZE = 64 -- default size of receive
buffer
+ const SERIAL_RCVBUFSIZE = 64 -- default size of receive
buffer
end if
if (defined(SERIAL_DELTA) == false) then
- const SERIAL_DELTA = 17 -- default spare space receive
buffer
+ const SERIAL_DELTA = 17 -- default spare space
receive buffer
end if
-if (defined(serial_hw_baudrate) == false) then
+if (defined(serial_hw_baudrate) == false) then
if (defined(SERIAL_BPSRATE) == true) then
_warn "SERIAL_BPSRATE is deprecated - please use serial_hw_baudrate"
- const serial_hw_baudrate = SERIAL_BPSRATE
+ const serial_hw_baudrate = SERIAL_BPSRATE
else
pragma error -- no baudrate defined
end if
@@ -143,26 +143,34 @@
include usart_common
--- Declaration of local circular buffers for communications via UART:
-
+-- Local circular transmit buffer
var byte _serial_xmtbuf[SERIAL_XMTBUFSIZE] -- circular output buffer
+
+-- Local circular receive buffer
var byte _serial_rcvbuf[SERIAL_RCVBUFSIZE] -- circular input buffer
-- Declaration of local offsets in circular buffers:
+-- variable keeping track of next free position in transmit buffer
var byte _serial_offsetxmthead -- offset next byte from
appl
+
+-- variable keeping track of next byte to be transmitted by interrupt
handler
var byte _serial_offsetxmttail -- offset next byte to port
+
+-- variable keeping track of next free byte in receive buffer
var byte _serial_offsetrcvhead -- offset next byte from
port
+
+-- variable keeping track of next byte available to application program
var byte _serial_offsetrcvtail -- offset next byte to appl
--- Declaration of internal flag
-var bit serial_send_success -- serial_send_success is used internally to
- -- pass information from serial_send_byte to
- -- serial_hw_write and serial_hw_data'put
+-- Flag indicating if transmission was successful
+var bit serial_send_success -- serial_send_success is used internally
+ -- to pass information from serial_send_byte
+ -- to serial_hw_write and serial_hw_data'put
-- without breaking the serial_send_byte API.
-- ----------------------------------------------------------------------
--- UART - serial transmit interrupt handling
+-- USART serial transmit interrupt handler
-- ----------------------------------------------------------------------
procedure _serial_transmit_interrupt_handler() is
@@ -170,7 +178,7 @@
var byte x
- if ((PIR1_TXIF == TRUE) & (PIE1_TXIE == TRUE)) then -- UART xmit
interrupt
+ if ((PIR1_TXIF == TRUE) & (PIE1_TXIE == TRUE)) then -- UART
xmit interrupt
if (_serial_offsetxmttail != _serial_offsetxmthead) then -- data in
xmit buffer
x = _serial_xmtbuf[_serial_offsetxmttail] -- next
byte to xmit
_serial_offsetxmttail = _serial_offsetxmttail + 1 -- next
position
@@ -188,7 +196,11 @@
-- ----------------------------------------------------------------------
--- - UART - serial receive interrupt handling
+-- USART serial receive interrupt handler
+--
+-- notes: - Sets CTS low when receive buffer has less than <SERIAL_DELTA>
+-- bytes free space.
+--
-- ----------------------------------------------------------------------
procedure _serial_receive_interrupt_handler() is
@@ -212,18 +224,18 @@
else -- data without errors
_serial_rcvbuf[_serial_offsetrcvhead] = RCREG -- move byte
to rcv buffer
-
+
if (defined(serial_receive_wedge) == true) then
-- receive wedge - a user program can define this procedure.
-- procedure serial_receive_wedge(byte in char)
-- If this procedure exisits, it will be called from the
- -- isr for each received char.
+ -- isr for each received char.
-- CAUTION: the wedge is part of the ISR and should be designed
-- to behave accordingly. If you are not sure you need this,
you
-- probably don't!
serial_receive_wedge(_serial_rcvbuf[_serial_offsetrcvhead])
end if
-
+
x = _serial_offsetrcvhead + 1 -- update offset
if x >= SERIAL_RCVBUFSIZE then -- buffer overflow
x = 0 -- wrap
@@ -257,10 +269,10 @@
--
-- output: received byte (if any)
--
--- returns: true when byte returned
--- false if no byte available
+-- returns: TRUE when byte returned
+-- FALSE if no byte available
--
--- notes: - Rises CTS when receive buffer has more than <DELTA>
+-- notes: - Sets CTS high when receive buffer has more than <SERIAL_DELTA>
-- bytes free space after delivering byte to caller.
--
-- ----------------------------------------------------------------------
@@ -292,6 +304,7 @@
end function
+-- Deprecated
function serial_receive_byte(byte out data) return bit is
pragma inline
_warn "serial_receive_byte() is deprecated - please use
serial_hw_read()"
@@ -318,8 +331,8 @@
var byte newxmthead -- offset in circular
buffer
- serial_send_success = true -- indicate byte sent
-
+ serial_send_success = true -- indicate byte sent
+
if (_serial_offsetxmthead == _serial_offsetxmttail & -- nothing
buffered
PIR1_TXIF == true) then -- and UART not busy
PIE1_TXIE = FALSE -- disable xmt interrupt
@@ -338,7 +351,7 @@
-- nothing -- spin until something
xmit'd
end loop
_serial_offsetxmthead = newxmthead -- update offset
- else
+ else
serial_send_success = false -- indicate byte discarded
data = 0x00 -- indicate byte discarded
end if
@@ -370,7 +383,7 @@
-- TXSTA_BRGH = true -- high baud rate
-- SPBRG = (target_clock / 16 / serial_hw_baudrate * 10
- 5) / 10
_calculate_and_set_baudrate() -- set baudrate
-
+
PIE1_RCIE = enabled -- UART receive int. enable
-- (PIE1_TXIE dynamically)
INTCON_PEIE = enabled -- periferal
@@ -380,6 +393,8 @@
end procedure
+
+-- Deprecated
procedure serial_init() is
_warn "serial_init() is deprecated - please use serial_hw_init()"
serial_hw_init()
@@ -388,32 +403,40 @@
-- ----------------------------------------------------------------------
--- serial_hardware compatible interface
+-- serial_hardware compatible interface
-- ----------------------------------------------------------------------
+
+-- Transmit byte
procedure serial_hw_data'put(byte in data) is
+
var byte dummy
-
+
serial_send_success = false
while (serial_send_success == false) loop
dummy = serial_send_byte(data)
end loop
-
-end procedure
-
-function serial_hw_data'get() return byte is
- var byte data
- while ! serial_hw_read(data) loop end loop
- return data
-end function
+end procedure
+-- Transmit byte
procedure serial_hw_write(byte in data) is
var byte dummy
-
+
serial_send_success = false
while (serial_send_success == false) loop
dummy = serial_send_byte(data)
end loop
-
+
end procedure
+
+
+-- Return next received byte
+function serial_hw_data'get() return byte is
+ var byte data
+ while !serial_hw_read(data) loop
+ -- nothing
+ end loop
+ return data
+end function
+
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
