# concepts of inversion and assertion. Reviewed slaa089d and slaa096d;
# no changes required due to updated documentation.
#
-# Important conventions used in this code
-# =======================================
+#
+# Set and clear of digital signals
+# ================================
+#
# All functions that can set or clear a digital pin or signal state do so
-# relative to the assertion state of its signal. That is, SetXXX(1) asserts
-# signal XXX and SetXXX(0) unasserts signal XXX. Asserting a signal means its
+# relative to the assertion state of its signal. That is, setXXX(1) asserts
+# signal XXX and setXXX(0) unasserts signal XXX. Asserting a signal means its
# logic value is set to that value that asserts, or activates, its condition.
# Signals may be either active high or active low, as shown in the chart below.
#
# active --- value --- --- value ---
# state logic voltage logic voltage
# ----------------------------------------
-# high 1 Vcc 0 GND
-# low 0 GND 1 VCC
+# high 1 Vcc 0 GND
+# low 0 GND 1 VCC
+#
+# It is the responsibility of the setXXX functions to properly convert the
+# set request into the proper output value. This provides a consistency for
+# applications using the set functions, since they no longer care the manner
+# in which an asserted or unasserted signal are actually represented in the
+# transmission medium.
#
#
# Important information about RS-232C signals
# ===========================================
#
-# Setting RS-232 signals, like DTR and RTS, from a host using Python using the
-# convention defined above:
-# A signal is asserted by calling serial.setXXX(1) [Ex: setDSR(1)]
-# A signal is unasserted by calling serial.setXXX(0) [Ex: setRTS(0)]
+# RS-232C signals are active low. Confusingly, however, RS-232C physical
+# drivers effectively invert the value, such that a high value, or MARK, is
+# delivered over the wire as a negative voltage while a low value, or SPACE, is
+# delivered as a positive voltage. By looking at an RS-232C signal on an
+# oscilloscope, one might conclude that the RS-232C signals are active high for
+# this reason. Here is how RS-232 breaks down:
#
-# RS-232C signal output mechanics:
-# An asserted RS-232C DTR or RTS signal is simultaneously:
-# logic 0
-# A SPACE condition
-# Has a voltage between +3v and +15v per the RS-232C specification
-# TTL level RS-232C pins use Vcc to indicate the logic 0 / SPACE condition
-# An unasserted DTR or RTS signal is simultaneously:
-# logic 1
-# A MARK condition
-# Has a voltage between -3v and -15v per the RS-232C specification
+# signal logical RS-232C RS-232C TTL RS-232
+# state value value name output voltage output voltage
+# ---------------------------------------------------------------
+# asserted 0/low SPACE +3v...+15v GND (0V)
+# unasserted 1/high MARK -3v...-15v VCC
#
-# PC serial ports often break the spec and use 0v to indicate logic 1/MARK
+# Note that some RS-232 signals, notably TxD (transmit data) and RxD (receive
+# data), can be idle. An idle signal is always unasserted.
#
-# TTL level RS-232C pins use GND to indicate the logic 0/SPACE and Vcc to
-# indicate logic 1/MARK
+# Using this guidance, an asserted DTR signal is logic low, is 0V in TTL RS-232
+# and +3V..15V in RS-232C.
#
-# RS-232C signal lines are active low, in that the asserted signal is
-# represented by a logic zero (0).
+# PC serial ports often break the spec and treat 0v as a logic 1/MARK instead
+# of an invalid value.
#
#
# Important MSP430 signals
# The BSL protocol is entered by manipulating the RST and TCK pins on MSP430
# uC's with dedicated JTAG pins, and by manipulating RST and TEST pins on
# MSP430 uC's with shared JTAG pins. The assertion state of TEST and TCK
-# are always equal, so we use the term TTCK to imply either or both of them
+# are the same, so we use the term TTCK to imply either or both of them
# simultaneously.
#
# RST and TCK are active low signals. TEST is active high.
# An MSP430 is reset by simplying asserting RST for a short period then
# unasserting it.
#
-# The BSL mode is entered by performing this sequence of events:
+# The BSL mode is entered by performing this sequence of events, subject to
+# timing constraints documented by TI:
# Assert RST
# Assert TTCK
# Unssert TTCK
# that can vary significantly from the TI schematic.
#
# The code presented in the TI document does not use a consistent methodology
-# to indicate what is happening when a SetXXX(n) function is called. In some
+# to indicate what is happening when a setXXX(n) function is called. In some
# cases, 'n' represents the assertion state, where 1=asserted and 0=unasserted.
# In other cases, 'n' represents the inverse of the assertion state. In yet
# other cases, 'n' represents the logic value of the signal on a given pin, or
# the inverse of the logic value.
#
-# To improve readability, this code explicitly defines all SetXXX(n) functions
-# where 'n' represents the assertion state of the signal. In other words, when
-# n==1 the signal is asserted and when n==0 the signal is unasserted. One can
-# trivially determine the logic state of any signal pin by applying the current
-# assertion state to the signal's active state (see the chart above).
+# To improve readability and allow for modular, pluggable BSL handling, this
+# code explicitly defines all setXXX(n) functions where 'n' represents the
+# assertion state of the signal. In other words, when n==1 the signal is
+# asserted and when n==0 the signal is unasserted. One can trivially determine
+# the logic state of any signal pin by applying the current assertion state to
+# the signal's active state (see the charts above).
#
# Device support
# ==============
projects / tinyos-2.x.git / commitdiff