Path: utzoo!utgpu!water!watmath!clyde!bellcore!decvax!decwrl!sun!pitstop!sundc!seismo!uunet!steinmetz!itsgw!imagine!pawl17.pawl.rpi.edu!jesup
From: jesup@pawl17.pawl.rpi.edu (Randell E. Jesup)
Newsgroups: comp.sys.amiga
Subject: Re: Multiple serial ports
Message-ID: <219@imagine.PAWL.RPI.EDU>
Date: 16 Jan 88 05:15:53 GMT
References: <2245@cup.portal.com> <22374@ucbvax.BERKELEY.EDU> <202@imagine.PAWL.RPI.EDU> <530@nuchat.UUCP> <217@imagine.PAWL.RPI.EDU>
Sender: news@imagine.PAWL.RPI.EDU
Reply-To: beowulf!lunge!jesup@steinmetz.UUCP
Organization: RPI Public Access Workstation Lab - Troy, NY
Lines: 190

[ This is cross-posted from BIX, and is (I hope) very thorough.  It mainly
  addresses using icons in the expansion drawer, but also weighs the pros
  and cons of my proposals, and gives example code and data structures. ]

[These are taken from drivers.doc of the gamma readmes.]

...
< your driver code:
<     Find the list of boards.  Mark them a configured, and record
<     your driver in them (for system debugging).  return non-zero
<     value if everything went ok.  If something went wrong (or you
<     just want to be unloaded) then return NULL.

...
< 4.  Attempt to load in the driver.  The driver may be a device, library,
<     task, process, or anything else that you may want.  The only requirement
<     is that it have a Resident structure in its first hunk.  (By the
<     way, this means that you can not directly use startup.obj).  This
<     is why we refer to loading a "driver" rather than a "device" -- you
<     can write any sort of code you want to handle your device.
< 
< 5.  Binddriver will search the first hunk for a Resident structure.
<     If it cannot find one, it will assume some awful mistake has
<     been made, and will unload the segment.
< 
< 6.  Finally we get to running some of YOUR code.  InitResident() is
<     used to start you off and running.  The return value from
<     InitResident (and therefore the return value from your init
<     entry point) will be checked on exit.  If it is zero then the
<     segment will be unloaded.  This can be useful if you only
<     need to do a bit of initialization and then can go away, such
<     as allocate additional expansion memory for a non-expansion
<     architecture board.
< 
<     You should (among everything else you might be doing) open
<     the expansion.library and ask for the current bindings
<     (GetCurrentBinding()).  In this structure will be the head
<     of a singly linked list of ConfigDev structures.  The structures
<     are linked via the cd_NextCD field.  You should deal with
<     each member of the list -- they are for you!
< 
<     There are two actions that you MUST take.  One is to unset
<     the CDB_CONFIGME bit in the cd_Flags.  If you do not do this
<     then the board is still available for other drivers (of course,
<     you may actually want this...).  If you do unset the CONFIGME
<     bit, please also record your "node" in the cd_Driver structure.
<     It is assumed that this is an exec node, whose LN_NAME field
<     points your your name, and LN_TYPE field is your type of "thing" --
<     libarary, resource, device, task, etc.  I know that this will
<     not always hold, but try it anyway.  It will help the rest of
<     us debug the system when something goes wrong.
< 
<     You have now done everything you wanted to.  Your init routine
<     is about to return.  If you return a zero, then your code
<     will be unloaded.  If you return non-zero then you will stay
<     around.

[end insertion]

	It looks like it's quite easy to set up a small program that
will be unloaded after it adds your device to the list of serial
devices.  Just return NULL and you are unloaded.  I would suspect that
any hardware manufacturer would want to have some sort of expansion drawer
code anyway, if only to watch for multiple boards so they can be handled by
one driver.

	So the code attached to the icon would look like this:

	<startup>
	<find boards, do any magic required>
	<if serial_exp.library doesn't exist:>
		<create it>
		<create handler entry for XSER:, to be loaded on reference>
		/* This avoids using the mountlist, requires no code loaded */
	For each board you are handling...
	  <get the disk object>
	  <make a node for the board, record any info needed>
	  For each unit...
	    <look for tooltypes describing the names bound to the units>
	    <add them to the node>
	<if your driver is not in ROM and not here, exit NULL>
	<else start driver up, return appropriate non-null>

	The idea is that the driver could live in devs, and not be forced to
be loaded at boot, only when needed.  The hardware manufacturer could decide
otherwise, if they wished.

	These next two lists refer to the proposal to add a name-mapper
with expansion drawer icons/programs to set up the mapping, as discussed.
One could use a config file instead of expansion drawer icons, but I
consider that sub-optimal.  The advantages listed are for my proposals,
as elaborated, over increasing unit numbers via a high priority serial
device, and over a config file for namings.

Advantages:
	1.  The resident data on serial ports/units means that when you
	    open a serial port, no searching of directories has to be done
	    (glacial on floppies).
	2.  It (resident data) means no naming conventions for drivers are
	    needed, which should make maintenance easier.
	3.  The resident data has very small overhead compared to a whole
	    driver.
	4.  If you remove a board, there is no need to remove it from
	    any master config files, or even remove the drivers or files
	    in the expansion drawer, as expansion drawer programs are only
	    run if the matching board is present.
	5.  Expansion ports are always known by name or function, not
	    by user-obtuse or volitile numbers.  Less programs will need
	    to be configured by the user, as they can just, for example,
	    open a modem, and the user doesn't have to remember that
	    unit 5 is a modem, for example.
	6.  No overhead after the OpenDevice, as the IOExtSer passed is
	    initialized with the device address by the driver that is
	    eventually opened.
	7.  No confusion over how unit numbers are assigned.
	8.  No naming conflicts with serial.device (Bryce states that his
	    serial.device links in at higher priority.  This works, but
	    only if his serial.device is loaded AFTER the old serial.device
	    AND if it is created by a program (you can't have two files
	    named "serial.device" in the devs: directory.))
	9.  Less problems from some programs using higher unit numbers,
	    and others using name mapping (Bryce agrees a name-mapper
	    should exist, but is trying to persuade people to use higher unit
	    numbers, and has posted no real design for a name-mapper.)
	10. Relatively "clean" design, oriented towards the same ideas
	    that the expansion standards are: drop it in, no careful setting
	    of switchs, no hacker needed to configure it.

Disadvantages:

	1.  Requires the user run a program so the file can get in
	    devs:.  (This applies to all schemes that put drivers there,
	    however, so it's no real loss.  Plus something needs to make
	    sure for all schemes that some new software is installed,
	    so it's even less of a loss.)
	2.  Requires a prefs-type program to change names for units,
	    instead of editing a file with a text editor.  Can also
	    be seen as a plus, as most novices don't know how to get to
	    a text editor, let alone how to use one (requires CLI unless
	    you have PD/whatever stuff - Notepad doesn't count here.)
	3.  Requires a small amount of ram for the fake library and
	    the nodes for each device/unit.  This is pretty minimal
	    compared with forcing a driver (even one) to be resident.
	4.  Requires serial device users to add 5 or so lines to their
	    OpenDevice calls, which can be standardized.  Not a big
	    overhead, less than the code required to let the user change
	    the unit number, probably.
	5.  ??? (I'm obviously biased, add you own here.)


Appendix:  Structures and code fragments related to above

	struct IOExtMap {
		struct IORequest ior;
		struct IOExtSer *Serial;
		ULONG  Flags;
		ULONG  Error;
		UBYTE  *Name;
		/* I think that's all we need */
	};

	Code for user program instead of OpenDevice("serial.device",0,...)

	<set up IOExtSer as always>
	myIOExtMap.Serial = &myIOExtSer;
	myIOExtMap.Flags  = MAPFLAGS;
	myIOExtMap.Name   = "Modem";
	myIOExtMap.Error  = 0;		/* probably redundant */

	if (OpenDevice("mapper.device",0,&myIOExtMap,0))
		if (myIOExtMap.Error != 0)
			/* mapper exists but can't open desired device */
			report some error
		else if (OpenDevice("serial.device,0,&myIOExtSer,0))
			report error

	/* the else clause is if the user doesn't have */
	/* the serial expansion software. */

	/* If we get here without error, we can use IOExtSer */

This is being cross-posted to Bix and Usenet.

	Randell Jesup


     //	Randell Jesup			      Lunge Software Development
    //	Dedicated Amiga Programmer            13 Frear Ave, Troy, NY 12180
 \\//	beowulf!lunge!jesup@steinmetz.UUCP    (518) 272-2942
  \/    (uunet!steinmetz!beowulf!lunge!jesup) BIX: rjesup