specification

mpc8xx driver(led), based on tqm8

#######################################################################
#
# (C) Copyright 2000
# Jean-Jacques Germond, Fr閐閞ic Soulier, Christian Batt; Alcatel
# C/O [e-mail]
#
# All rights reserved.
#
# This code is free software; you can redistribute it and/or
# modify it under the terms of the GNU *Library* General Public License
# as published by the Free Software Foundation; either version 2 of
# the License, or (at your option) any later version.
#
# This code is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# *Library* General Public License for more details.
#
# You should have received a copy of the GNU *Library* General Public
# License along with this program (see file COPYING.LIB); if not,
# write to the Free Software Foundation, Inc., 675 Mass Ave,
# Cambridge, MA 02139, USA.
#
#######################################################################

Subject: tid : trivial interrupt driver.


In order to learn about interrupt drivers, Linux and Linux port on
MPC8xx, we are going to write a "Trivial Interrupt Driver" (tid) that
will be generic MPC8xx.

We will use one of the many timers that are available on the CPM and
operate it under interrupt in periodic mode. (that is NOT in one shot
mode).

Upon interrupt, the driver will write some stuff in a pseudo device
that can eventually be read by Unix processes.

We try to carefully use the name 'device' for the unique entity that
stores bytes and the name 'file' for the potentially several UNIX
entity that are independdently used to read the 'device'.


The stuff in question is defined in the following manner.

a) The number of bytes in the device is equal to the number of timer
   interrupts since last reset (see below about reseting this
   number), in order to limit stdout, the number of such chars will
   be restricted to a compile time constant.

b) Bytes in the device do not use any memory since they form a
   deterministic ripple pattern such as:

       abcd.......xyz102....789
       bcd.......xyz102....789a
       cd.......xyz102....789ab
       ....

c) To reset the the number of bytes in the device, just open a filee
   in write mode to it. This permits to test tid with std unix tools
   such as cat and cp.

   ex:
	# This exemple assumes that:
        #   -The timer frequency is in the range of few interrupts
        #    per seconds
        #   -commands are typed at a 'reasonable' speed
        #   -the stdout console is 'quite' faster than teh timer in terms
        #    of chars per seconds.

	insmod the tid driver.
        wait form some its
        cat /tmp/tid   # Show 'some' ripple lines
        wait again
        cat /tmp/tid   # Show more rippled lines

        # Reset tid the device and show very few chars if any.
        echo 'toto' > /dev/tip ; cat /dev/tid


For the sake of training, the following functionalities will be put
to work:

	-TOP HALF and BOTTOM HALF code.

        -The Unix processes will be blocked or not (according to an
         open flag) if the pseudo file is empty at read time.

	- /proc

The driver will be layered upon a "virtual" timer exporting the
following interface.

    void tid_init_timer (Tid_Dev* dev, unsigned long period);

	/*
	 * Initialize timer hardware, configure interrupt handling,
	 * start timer
	 */

    void tid_cancel_timer (Tid_Dev* dev);

	/*
	 * Stop timer, deactivate interrupt handling
	 */

    void tid_setPeriod(Tid_Dev* dev, ulong period);

	/*
	 * Set period in microseconds and start. Always work.
	 * Stop timer and timer interrupt if arg is zero.
	 * Truncate period to maximal possible value.
	 */

    void tid_ackTimerInterrupt(void *dev_id);

	/*
	 * Do necessary hardware actions
	 */