Tews Technologies TIP815-SW-12 User manual

TIP815--SW--12
OS--9 Device Driver
for TIP815 ARCNETInterfaceIP
Version1.4
Revision1.1
22 June 1999
TEWSDATENTECHNIKGmbH
AmBahnhof7
D--25469 Halstenbek
Germany
Tel.:[phone]
Fax:[phone]
EMail:[e-mail]
Web:http://www.tews.com

TIP815--SW--12
ARCNETInterfaceIP
OS--9DeviceDriver
Thisdocumentcontainsinformation,whichisproprietaryto TEWSDATENTECHNIKGmbH.Any
reproduction withoutwrittenpermission isforbidden.
TEWSDATENTECHNIKGmbHhasmade anyeffort toensurethat thismanual isaccurate and
complete.HoweverTEWSDATENTECHNIKGmbHreservestheright tochangetheproduct
describedinthisdocumentatanytimewithoutnotice.
Thisproducthasbeendesignedtooperatewith TEWSDATENTECHNIKGmbH’sTIP815ARCNET
InterfaceIndustryPackrcompatiblemodule.
TEWSDATENTECHNIKGmbHisnotliableforanydamagearisingoutoftheapplicationoruseofthe
softwaredescribedherein.
e1999 byTEWSDATENTECHNIKGmbH
IndustryPack isaregisteredtrademarkof GreenSpringComputers,Inc

1.Introduction 3.........................................
2.Installation 4..........................................
3.I/Ointerfacefunctions 5.................................
3.1.t815_open() 5..............................................
3.2.t815_close() 6..............................................
3.3.t815_read() 7...............................................
3.4.t815_write() 9..............................................
3.5.t815_cntrl() 11...............................................
4.DeviceDescriptor 15.....................................
5.Appendix 16............................................
5.1.Predefined Symbols16........................................
5.2.Statusand ErrorCodes17.....................................

3
1. Introduction
TheTIP815--SW--12 OS--9devicedriverallowstheoperation oftheTIP815 ARCNETIPwitha
device--independentinterfacewitht815_open,t815_read,t815_writeandt815_cntrlfunctions.
AfterinstallationofthedevicedriverintheI/Osystemmessagescanbetransmittedtoandreceived
fromtheARCNETInterfacebycallingthet815_write() ort815_read() functions.
SpecialI/Ooperation thatdo notfit tothestandardI/Ocallswill beperformed bycallingthe
t815_cntrl() function withaspecificfunction code andan optionalfunction--dependentargument.
Thisdriverinvokeamutualexclusionandqueuingmechanismtopreventsimultaneousrequestsby
multipleusersfrominterferingwitheach other.

4
2.Installation
TheTIP815--SW--12 OS--9driversoftwareisdeliveredon a 3.5” floppydisc.
Thefloppyhasfollowingcontents:
/d0/tip815/t815driv.cTIP815 devicedriverCsource
/d0/tip815/t815adriv.aTIP815 devicedriverassemblertoC interface
/d0/tip815/t815cif.aTIP815 devicedriverapplication call interface
/d0/tip815/t815stat.aTIP815 devicestaticstorage allocation
/d0/tip815/t815A.aTIP815 devicedescriptorIP- -slotA(MVME162)
/d0/tip815/t815B.aTIP815 devicedescriptorIP- -slotB(MVME162)
/d0/tip815/t815C.aTIP815 devicedescriptorIP- -slotC(MVME162)
/d0/tip815/t815D.aTIP815 devicedescriptorIP- -slotD(MVME162)
/d0/tip815/tip815.hTIP815 application programinclude
/d0/tip815/local.hTIP815 devicedriverinclude
/d0/tip815/ipchip.hMVME162 IPchip definitions
/d0/tip815/arcnet.hARCNETcontrollerprogrammingmodel
/d0/tip815/makefileMakefiletobuildthedriver
Thedistribution containspredefined devicedescriptorsforthefourIP slotsoftheMVME162.
DescriptorAddress VectorLevel
t815A0xfff58000 0x80 1
t815B0xfff58100 0x81 1
t815C0xfff58200 0x82 1
t815D0xfff58300 0x83 1
Afteryou’vecopiedall filesfromthedisk,you havetochoosetheversion ofyourOS--9.Edit the
Makefile andenablethelinesettingtheflagsforyourOS--9version:
$eMakefile
Afteryou choosetheusedOS--9version, thedrivercanbebuildwiththefollowingcommand:
$make
Thedriveranditscorrespondingdevicedescriptorscanbeloadedintotherunningsystemwiththe
command:
$load--dt815drvt815At815Bt815Ct815D
Thedevicedrivermustbeinitializedforeachdevicedescriptorwithacommandlike:
$inizt815A...
AllTIP815I/Osystemcalls(t815_open(),t815_close()andt815_cntrl())canbecalleddirectlyoutof
theC--code application programbyusingtheCcall interface.
To dothisitisnecessarytolinktherelocatableobjectt815cif.rwiththe application program.
Forexample:$cc ... program.ct815cif.r...

5
3.I/O interface functions
ThischapterdescribestheinterfacetotheI/Osystemusedforcommunication overtheARCNET
Interface.
3.1. t815_open()
NAME
t815_open() - - openapathtoaTIP815 device
SYNOPSIS
int t815_open(DeviceName,PathNr )
char*DeviceName;/*nameofthedeviceto open*/
int*PathNr;/*path number returned bythiscall */
DESCRIPTION
BeforeI/OcanbeperformedtotheTIP815 deviceitmustbeopened byinvokingtheI/O function
t815_open().
Thepath numberisusedtoidentifythedeviceinsubsequentservicerequests.
EXAMPLE
...
/*- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -
openthedevicenamed”/t815A” forI/O
- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -*/
result=t815_open(”/t815A”,&path);
....
RETURNS
returnsE_NOERR(0)ifthedevicewassuccessfulopened,oranappropriateerrorcodeifthedevice
doesnotexist.
SEE ALSO
I/Osystemcall I$Open

6
3.2. t815_close()
NAME
t815_close() - - close a pathtoaTIP815 device
SYNOPSIS
int t815_close(PathNr )
intPathNr;/*path number*/
DESCRIPTION
TerminatestheI/Opathspecified by PathNr.
RETURNS
returnsE_NOERR (0)ifthedevicewas successfulclosed,oranappropriate errorcode.
SEE ALSO
I/Osystemcall I$Close

7
3.3. t815_read()
NAME
t815_read() - - readamessagefromspecifiedTIP815 device
SYNOPSIS
int t815_read(PathNr,io_flags,MsgBuf)
intPathNr;/* Path number*/
intio_flags;/*I/O flags:[T815_FLUSH|T815_NOWAIT]*/
T815_MSG*MsgBuf;/* Pointertothemessagebuffer*/
DESCRIPTION
Once a TIP815 devicehasbeen opened, taskscanreadmessagesfromthedevice.
Becausemoreinformationsasthepuredatabytesarerequiredforthereadrequestwehave
designedaspecialI/Odatastructure(T815_MSG).
ThisdatastructurecontainsthereceivedDataPacketwithsource and destination ID,message
lengthandmessagedata.
typedefstruct{
unsignedcharSID;/*Source ID*/
unsignedcharDID;/*DestinationIDor0forbroadcasts */
unsignedshortlen;/*Messagedatalength*/
unsignedchardata[MAX_LONG_MSG];/*Messagedata*/
/*253 bytesforshortpackets */
/*508 bytesforlong packets */
}T815_MSG;
IftheI/OflagT815_FLUSHisset, aflushofthereadringbufferwillbeperformedbeforeactivationof
thereadrequest.
Ifthedeviceisblockedbyanotherreadrequestornomessageisavailableinthereadbufferandthe
I/O flagT815_NOWAITisnotset, therequestingtaskwill beblockeduntil amessagewasread.
Aftersuccessfulcompletion ofareadrequestSIDcontainstheSourceID,DIDcontainsthe
Destination ID,len thenumberofdatabytesanddata[] thereceivedmessage.

8
EXAMPLE
#include”tip815.h”
{T815_MSGrcvbuf;
intstatus;
intpath;
status=t815_open(”/t815A”,&path);
/*readamessagefromopenedTIP815 device.
oflushtheinputring bufferbeforereading
oreturnimmediatelyifthereisno message available
*/
status=t815_read(path,T815_FLUSH|T815_NOWAIT,&rcvbuf);
if(status== E_NOERR){
/*process message*/
}
else{
/*handledevice error*/
}
}
RETURNS
E_NOERR ifreadwas successfuloranappropriate errorcode
INCLUDEFILE
tip815.h

9
3.4. t815_write()
NAME
t815_write() - - write a messagetospecifiedTIP815 device
SYNOPSIS
int t815_write(PathNr,io_flags,MsgBuf)
intPathNr;/* Path number*/
intio_flags;/*I/O flags:[T815_NOWAIT]*/
T815_MSG*MsgBuf;/* Pointertothemessagebuffer*/
DESCRIPTION
Thisroutinewrite a messagetothespecifiedTIP815 device.
Becausemoreinformationsasthepuredatabytesarerequiredforthewriterequestwehave
designedaspecialI/Odatastructure(T815_MSG).
ThisdatastructurecontainstheDataPacketwithsource and destination ID,messagelengthand
messagedata.
typedefstruct{
unsignedcharSID;/*Source ID*/
unsignedcharDID;/*DestinationIDor0forbroadcasts */
unsignedshortlen;/*Messagedatalength*/
unsignedchardata[MAX_LONG_MSG];/*Messagedata*/
/*253 bytesforshortpackets */
/*508 bytesforlong packets */
}T815_MSG;
TheparameterSID isnotused.
TheparameterDIDspecifiestheDestination ID(Destination nodehardware address).
Theparameterlenspecifiesthenumberofdatabytes(data[])tobetransferred.Thenumberofdata
bytesislimitedto253 bytesforshortpacketsand508 bytesforlong packets.
TheonlyvalidI/O flagsetinio_flagsisT815_NOWAIT.If thisflagis set, t815_write() returns
immediatelyafterstartingtransmission,otherwiset815_write()waituntilthemessageistransmitted
andacknowledgedoranerroroccur.
If thedeviceisblocked byan otherwriterequest, therequestingtaskwill beblockeduntil the
transmitterbecomefree ortherequest timesout.

10
EXAMPLE
#include”tip815.h”
#defineHELLO”HELLOOOO WORLD”
{T815_MSGsndbuf;
intstatus;
intpath;
...
status=t815_open(”/t815A”,&path);
/*
t815_write a messagetoaTIP815 device.
*/
sndbuf.DID=123;
sndbuf.len=14;
memcpy(sndbuf.data,HELLO,14);
status=t815_write(path,0,&sndbuf);
if(result!=E_NOERR){
/*handledevice error*/
}
....
}
RETURNS
E_NOERR ifwritewas successfuloranappropriate errorcode
INCLUDEFILES
tip815.h

11
3.5. t815_cntrl()
NAME
t815_cntrl() - - performanI/Ocontrolfunction
SYNOPSIS
int t815_cntrl(PathNr,io_flags,function,arg)
intPathNr;/* Path number*/
intio_flags;/*I/O flags:[T815_BROADCAST| */
/*T815_LONGPACKET|T815_NODE_ID]*/
intfunction;/*function code[SS_MAP | SS_ONLINE| */
/*SS_OFFLINE|SS_DIAG|SS_FLUSH]*/
intarg;/*optionalfunction- -dependentargument*/
DESCRIPTION
SpecialI/Ooperation thatdo notfit tothestandard basicI/Ocallswill beperformed bycallingthe
t815_cntrl() function withaspecificfunction code andan optionalfunction- -dependentargument.
Followingfunctionsareimplemented:
SS_ONLINE- - InitializetheARCNETcontrollerandenteringthenetwork.
Afterdeviceinitialization theARCNETcontrollerisinresetstate andnot
connectedtothenetwork.TheI/OcontrolfunctionSS_ONLINEsetupthe
ARCNETcontrollerusinginformations specifiedintheT815_CONFIG.
Apointertotheconfigurationdata(T815_CONFIG)ispassedtothedriver
bythefunction- -dependentargumentarg.
ThestructureT815_CONFIGhasthefollowinglayout:
typedefstruct{
unsignedcharnode_id;/*nodeID*/
unsignedcharnetwork_timeout;
unsignedcharspeed;/*networkspeed*/
}T815_CONFIG;
PossibleI/O flags specifiedinio_flagsare:
T815_BROADCAST- - Configurethecontrollertoacceptbroadcast
messagesfromthenetwork.
T815_LONGPACKET- - Configurethecontrollertoreceivebothshort
andlong packets.If notsetonly shortpacketscanbereceived.
T815_NODE_ID- - UsenodeIDspecifiedin T815_CONFIG.If notset,
determinethenodeIDbyt815_readingthehardwareDIP switch.
Theparameternode_idspecifiesthenodeaddressonthenetworkforthis
node.ThisnodeIDisonlyusediftheI/OflagT815_NODE_IDis set.Valid
valuesare0to255.

12
Theparameternetwork_timeoutspecifiestheResponse,Idle andRecon
TimesoftheARCNETcontroller.All nodes should beconfiguredwiththe
sametimeoutvalueforpropernetworkoperation.
Validvaluesare:
for (TIP815- -10/- -20)
valueResponse(µs)IdleTime(µs)ReconfigTime(ms)
0 1130 1237 1680
1 563 624 1680
2 285 316 1680
3 78 86 840
for (TIP815- -11/- -21)
valueResponse(µs)IdleTime(µs)ReconfigTime(ms)
0 596.8 656 840
1 298.4 328 840
2 74.4 82 840
3 37.35 41 420
Thelastparameterspeeddeterminesthenetworkspeed by settingthe
clock prescalerto oneof fourpossiblevalues:
valuenetworkspeed
0 2.5Mbps
1 1.25 Mbps
2 625 Kbps
3 325.5Kbps
0xFF 5Mbps(onlyTIP815- -11/- -21)
Aftersuccessfulexecution ofSS_ONLINEtheARCNETcontrolleris
connectedtothenetworkandmessagescanbereceivedand
transmittedoverthenetwork.
SS_OFFLINE- - Shutdownthenodehardwareandremovethenodefromthenetwork.No
argumentsarerequiredforthiscall.To enterthenetworkagain usethe
t815_cntrlcommandSS_ONLINE.
SS_DIAG- - Getnumberofnodereconfigurations.Thenumberofnode
reconfigurationsreflectsthequalityofthenetwork.If thenumbergrows
upsoon thereis somethingwrongon thenetwork.
Thenumberofreconfigurationiscopiedtoanintegervariable,referenced
byapointerpassedtothedriverinthefunction- -dependentargument
arg.
Theinternalreconfiguration counterwill beresetafter reading.
SS_MAP- - Buildamapofnodescontainedon thenetwork.
Apointertoabufferispassedtothedriverinthefunction- -dependent
argumentarg.Bitsinthebufferareset(present)or reset(notpresent)
dependingonifanodeispresent.Thebuffermustbe32bytes(256bits)
inlength.Thefirstbyteinthe arraypresentsnodes0through7, the
second bytepresents8through15,andsoon.Theleastsignificantbitof
thebytepresentsthesmallestnodenumber.
SS_FLUSH- - ThisI/Ocontrolfunction flushesthereadring buffer.Noargumentsare
requiredforthiscall.

13
EXAMPLE
#include”tip815.h”
{intstatus;
intrecon;
unsignedcharmap[32];
intpath;
T815_CONFconf;
...
status=t815_open(”/t815A”,&path);
/*InitializetheARCNETcontrollerandenteringthenetwork
oacceptbroadcastmessagesfromthenetwork.
oreceivebothshortandlong packets
o usenodeIDspecifiedinnode_id
osetupnetworkspeedto2.5Mbps
oresponsetime=1130 µs
oidletime=1237 µs
oreconfigtime=1680 ms
*/
conf.node_id=9;
conf.network_timeout=0;
conf.speed=0;
status=t815_cntrl(path,
T815_BROADCAST|T815_LONGPACKET|T815_NODE_ID,
SS_ONLINE,
(int)&conf);
/*- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -
Getnumberofnodereconfigurations
- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -*/
status=t815_cntrl(path,0,SS_DIAG,(int)&recon );
printf(” %dreconfigurationsoccurredsincelastSS_DIAGcall\n”,recon);
/*- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -
Buildamapofnodescontainedon thenetwork
- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -*/

14
status=t815_cntrl(path,0,SS_MAP,(int)map);
if(map[1]&0x02)printf(” node9isavailable\n”);
/*- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -
Flushthet815_readring buffer
- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -*/
status=t815_cntrl(path,0,SS_FLUSH,0);
/*- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -
Shutdownthenodehardware andremovethenodefromthenetwork
- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -*/
status=t815_cntrl(path,0,SS_OFFLINE,0);
RETURNS
E_NOERR ifwritewas successfuloranappropriate errorcode
INCLUDEFILES
tip815.h

15
4.Device Descriptor
TheDevicedescriptorcontainall thatOS- -9needstoknowaboutadevice.All devicedescriptors
havesomebasicinformation incommon: the address ofthedevice, theinterruptvector,leveland
pollingpriority,whichfilemanagertousewithit(scf),whatdevicedrivertousewithit(t815driv)anda
deviceinitialization table.
PartofthedevicedescriptorusedforTIP815 mountedinslotA:
...
dc.l$FFF58000 Address ofport
dc.b$80 Vectortrapassignment
dc.b1IRQhardwareinterruptlevel
dc.b0IRQpolling priority
dc.bModeDevicemodecapabilities
dc.wFileMgrFilemanagernameoffset
dc.wDevDrvDevicedrivernameoffset
dc.w0Deviceconstantsoffset
dc.w0,0,0,0Reserved
dc.wOptSizOption bytecount
Options
dc.bDT_SCFDevicetypeSCF
OptSizequ*- -Options
FileMgrdc.b”Scf”,0Filemanager
DevDrvdc.b”t815driv”,0Drivermodulename
ModesetISize_+Updat_
Aftermodifyingsomeparameters, thedevicedescriptorcanbebuildwiththefollowingcommand:
$make

16
5. Appendix
5.1.PredefinedSymbols
Thefollowingsymbolsarepredefinedinthetheincludefiletip815.h.
t815_cntrlfunctioncodes
SS_MAP202 Buildamapofnodescontainedon thenetwork
SS_ONLINE203 InitializetheARCNETcontrollerandenteringthe
network
SS_OFFLINE204 Shutdownthenodehardware andremovethe
nodefromthenetwork
SS_DIAG205 Getnumberofnodereconfigurations
SS_FLUSH206 Flushthereadring buffer
I/Oflags
T815_FLUSH(1<<3)Flusht815_readring buffer
T815_BROADCAST(1<<4)Configurethecontrollertoacceptbroadcast
messagesfromthenetwork
T815_LONGPACKET(1<<6)Configurethecontrollertoreceivebothshortand
long packets.If notsetonly shortpacketscanbe
received
T815_NODE_ID(1<<7)UsenodeIDspecifiedin T815_CONFIG.If notset,
determinethenodeIDbyreadingthehardware
DIP switch
T815_NOWAIT(1<<8)Returnimmediatelyafterstartingtransmission

17
5.2.StatusandError Codes
E_NOERR 0Operation successfulcompleted
E_NXIO 0x100 No TIP815 devicefoundatspecified
address
E_ICMD0x102 Illegalt815_cntrlcommand
E_NOTACK0x104 NoACKfromreceiveraftertransmission
E_TIMEOUT0x105 Transmission timesout
E_QFULL 0x106 Thereadringbufferforincomingmessages
isfull
E_BAD_PACKET_SIZE0x107 Illegalnumberofbytestotransfer
E_DUPID0x108 Illegal(duplicate)nodeID
E_NETWORK_DOWN0x109 Noactivityon network
E_NODATA0x10ANomessagereceived(onlyif
T815_NOWAITis selected)
E_IO 0x10BDeviceI/Oerror ( controllererror)
E_NREADY0x10C Deviceisnotinitialized(SS_ONLINE)
E_BUSY0x10dThedeviceisbusy, thatmeansno reador
writejobsareavailableforthisrequestorthe
transmitterisbusy iftheI/O flag
T815_NOWAITis set.