home *** CD-ROM | disk | FTP | other *** search
/ PDA Software Library / pdasoftwarelib.iso / PSION / COMMS / P3NFS / README < prev    next >
Encoding:
Text File  |  1996-05-16  |  13.6 KB  |  307 lines
  1. INTRO
  2.   This package lets you mount the psion drives on your unix workstation
  3.   over a serial cable. You can access all the files from the psion with
  4.   the usual commands like tar, cp, vi & co.
  5.  
  6.   The Psion client is capable of terminal emulation (vt100/vt220 with
  7.   function key support) and it is fully functional without the Unix daemon.
  8.   New in Version 4.3:
  9.     - Fix for Linux 1.3.99
  10.     - Function key support for the terminal emulator.
  11.       In fact you can remap all your keys.
  12.  
  13.   License: GNU General Public Licence (Version 2)
  14.  
  15.   You have to be root in order to start the Unix program because it uses
  16.   the mount systemcall.
  17.   The current version was tested on SunOS 4.1.3, 4.1.4, 5.5, Irix 5.3 and
  18.   Linux 1.2.13, 1.3.99
  19.  
  20.   Author: Rudolf Koenig (rfkoenig@immd4.informatik.uni-erlangen.de)
  21.   Linux port by Juergen Weigert (jnweiger@immd4.informatik.uni-erlangen.de),
  22.   with help from Lee McLoughlin and others. 
  23.   Many thx to N.N., who returned test reports faster than we could compile.
  24.   IRIX port and many changes by Michael Schroeder. He is not (yet?) a Psion
  25.   owner.
  26.  
  27. CORRECTION:
  28.   p3nfsd is not really an nfs daemon. You can't mount the psion from
  29.   another workstation, only from the one, where it is attached to via
  30.   the serial cable. I used nfs, beause it is a portable way to capture
  31.   filesystem operations in a program. The daemon talks to the opl/c
  32.   program on the psion through a simple protocol.
  33.  
  34. COMPILING / INSTALLING:
  35.   First:
  36.     Make sure you know which operating system you are using:
  37.     % uname -a
  38.  
  39.     As the program depends on hardware flow control, you may need OS patches.
  40.     It's quite sure that won't get a correct transmission without proper
  41.     hardware flow control.
  42.  
  43.     Please check out the following list and verify, that you have the patch
  44.     installed. It is a good idea to search for newer patches.
  45.  
  46.     Supported Architectures:
  47.  
  48.     - SunOS 4.1.3
  49.       jumbo-tty patch from Nov 93, id 100513-4 is needed.
  50.     - SunOS 4.1.3_U1:
  51.       kernel patch 101621-02  'Jumbo tty patch',
  52.       available at the archive under pointer
  53.     http://src.doc.ic.ac.uk/sun/sun_fixes/sunos4.1.3_U1/101621-02.tar.Z
  54.       (reported by Oliver Meis (eedolm@aachen.ericsson.se))
  55.     - SunOS 4.1.4
  56.       I don't remember patching my machine, and it works quite well.
  57.     - Solaris 2.3/2.4/2.5
  58.       Use showrev -p to show the patches installed.
  59.       Solaris 2.3: patch 102028-01 (Sept. 94) for RTS/CTS is needed.
  60.                    (If somebody needs the patch, and has NO other way to
  61.             find it, ask caronni@tik.ethz.ch)
  62.       Solaris 2.4: patch 102029-01 _or_ 102845-02 (both of them fix RTS/CTS)
  63.            102029 should work, not tested
  64.                    102845 is newer, the README confused me, but works (tested)
  65.       Solaris 2.5: You don't need any patches, as the RTS/CTS patch was finally
  66.                    included
  67.     - Linux works without patches
  68.     - IRIX 5.3 should work without patches
  69.  
  70.   Compile nfsd
  71.     % cd nfsd
  72.     Uncomment the appropriate Makefile settings:
  73.     % vi Makefile (you can use other editors too :-)
  74.       If you don't see any lines for your OS, then you can go now to
  75.       the chapter PORTING, or free up some disk space.
  76.     Next check if you like the defaults
  77.     % vi ../include/config.h
  78.     and compile it
  79.     % make
  80.     If you want to run it as non-root:
  81.     # chown root /usr/local/bin/p3nfsd
  82.     # chmod 4711 /usr/local/bin/p3nfsd
  83.     It should be safe to run p3nfsd 4.2 as setuid root, unlike the previous
  84.     versions.
  85.  
  86.   nfsc4 
  87.     Note for S3 owners: I only tested it on my S3a in compatibility mode.
  88.     Some menu entries use shifted accelarators, this entries can only
  89.     called via the accelarators.
  90.     - If you have the Psion C SDK
  91.     In the nfsc directory, from the dos prompt:
  92.     C:\SIBOSDK\NFSC> makeshd nfsc
  93.     C:\SIBOSDK\NFSC> tsc /m nfsc
  94.     C:\SIBOSDK\NFSC> ren nfsc4.img nfsc4.app
  95.     - If you don't have the SDK you have to use the supplied nfsc4.app or
  96.       use the opl versions.
  97.     - If you do not need the terminal emulator, you can use nfscnovt.app,
  98.       it's only 9k instead of 19k.
  99.  
  100.   nfsc.opl
  101.     The opl programs are in the nfsc directory.
  102.     Note: there is an S3 version with no uadd in it.
  103.     Translate it on your psion. (Psion T in the Program editor)
  104.     A big advantage of the opl version that you can't set the serial
  105.     line parameters, and its 2k compiled instead of 17k.
  106.  
  107.   Setting up the mount directory:
  108.   # mkdir /psion.stand
  109.   # mkdir /psion.stand/mnt
  110.   # cd /psion
  111.   # ln -s mnt/loc::a: a
  112.   # ln -s mnt/loc::b: b
  113.   # ln -s mnt/loc::m: m
  114.  
  115. BOOTSTRAPPING:
  116.   (i.e copying nfsc.opl or nfsc4.app the first time to your psion)
  117.   You are here on your own.
  118.   You either have to use an existing method (PC, old nfsc, your friends SSD)
  119.   or you have to type in the opl program. (If somebody done the last one,
  120.   should mail me, she/he receives a free copy of p3nfsd :-)
  121.  
  122. STARTING IT:
  123.   First: Make sure the Serial Link is connected both to your unix machine
  124.   and to your psion.
  125.  
  126.   There are two basic ways of starting it, with or without the unix
  127.   getty/login occupying the serial line.
  128.  
  129. 1.Without the getty/login:
  130.   Make sure there is no getty running on the port:
  131.     SunOs 4.x: edit /etc/ttytab, set status to "off", wake up init: kill -1 1
  132.            Verify that the serial port has the softcarrier enabled. See
  133.            man ttysoftcar(1). This is only important if you plan to (or
  134.            not plan to but do) start the p3nfsd without a psion attached.
  135.     Solaris 2.x: disable the port with the admintool/serial port manager
  136.  
  137.   If using nfsc4, start it and set following parameters: 
  138.     Serial Line->Parameters:    Baudrate: 19200
  139.                       Databits: 8
  140.                 Stopbits: 1
  141.                 Parity:   none
  142.                 Ignore parity: no
  143.     Serial Line->Handshaking:    Hardware
  144.     Nfsc->Nfsd support:        Terminal + New p3nfsd
  145.   If using the opl client: You can't confuse anything on the opl client,
  146.   so just start it.
  147.  
  148.   On the unix machine type:
  149.   % p3nfsd -h (to see the options you can choose from)
  150.   % p3nfsd
  151.   or if using an opl client
  152.   % p3nfsd -oldnfsc  
  153.  
  154. 2.With the getty
  155.   Make sure the getty is running. SunOs: the softcarrier has to be enabled
  156.   here too. IRIX: Please use ttyf? instead of ttyd? for flow-control.
  157.   a. Log in.
  158.      Start nfsc, and set the correct serial line parameters:
  159.      Following works for a SunOs 4.x (Solaris 2.x) default setting.
  160.      Serial Line->Parameters:    Baudrate: 9600
  161.                       Databits: 7        (8 for Solaris 2.x)
  162.                 Stopbits: 1        
  163.                 Parity:   even        (none for Solaris 2.x)
  164.                 Ignore parity: yes
  165.   b.We now have to set the correct parameters for the nfsc/nfsd communication.
  166.     Each parameter is to set both on the psion and the unix host!
  167.     Following settings are required:
  168.  
  169.     change the baudrate if you wish:
  170.                unix: stty <baudrate>; nfsc Serial Line->Parameters->Baudrate
  171.     no parity  unix: stty -parenb; nfsc Serial Line->Parameters->Parity:none
  172.     1 stopbit  unix: stty -cstopb; nfsc Serial Line->Parameters->Stopbits: 1
  173.     8 databits unix: stty cs8; nfsc Serial Line->Parameters->Databits: 7
  174.     Hardware flow control
  175.                unix: stty crtscts,
  176.            nfsc Serial Line->Handshaking: Hardware
  177.     This changes are better made in the "Terminal only" mode, then switch
  178.     back to "Nfsc->Nfsd support:Terminal + New p3nfsd".
  179.     Now we can start the p3nfsd:
  180.     % p3nfsd -shell $SHELL -
  181.     You should get a new prompt, and the emulator should be faster.
  182.     WARNING: Do NOT use the -tty option with the getty running.
  183.  
  184.   If you wish to exit the nfsd type "ls <mntdir>/exit"
  185.  
  186. TESTING:
  187.   Try ls <mntdir>, if works ls -l <mntdir>.
  188.  
  189. FEATURES / TIPS:
  190.   - type p3nfsd -help to see all options.
  191.   - nfsc4 has a builtin terminal emulator (vt100/vt220),
  192.     and verifies a crc when reading or writing files to the nfsd.
  193.     The terminal emulator supports the 8 Standard fonts on the S3a
  194.     (Size 8 / 11 / 13 / 16, Swiss and Roman) plus the mini font
  195.     to allow for more than 20 (actually 27) lines. The last one can
  196.     only selected via psion z/Z and not from the fonts dialog.
  197.     If used with the nfsd -shell option, the resize is reported to the
  198.     application (SIGWINCH)
  199.     The alternate charset font is not complete, but boxes of any kind
  200.     should work.
  201.     The emulator is capable to display various vt100 animations.
  202.     Jumpscroll and charset conversion (ISO8859-1 <-> ibm codepage 850)
  203.     can be configured.
  204.     XYmodem was tested with the only Zmodem package I found for UNIX.
  205.     Xmodem works, Ymodem has a problem: the receiver won't terminate cleanly
  206.     after a file was sent. I think the Psion driver and the Unix program
  207.     behave differently here.
  208.     The emulator supports "Function Keys": i.e: you can specify a string 
  209.     to be sent when pressing a key. 
  210.     WARNING: It is possible to redefine each key received by the application.
  211.     There is a "novt" version of nfsc.app, which is about 10k smaller.
  212.  
  213.   - break. As there is no p_break() function or the like, the break is
  214.     generated as a series of 0 bytes sent at 50 baud. This can work, but
  215.     is not guaranteed, as the definition of break is 0 for at least 250ms
  216.     and this method generates more 200ms pieces. It works on SunOs, but not
  217.     on Solaris.
  218.   - there is a termcap entry / terminfo source file in the etc directory
  219.     which describes most capabilities, but vt100 or ansi should work.
  220.   - If you are using the C client as a terminal emulator only, please
  221.     switch it in the "Terminal only" mode: it is faster as the default
  222.     combined mode, which is for use with the p3nfsd -shell option.
  223.   - nfsd converts automatically all filenames from charset ibm850 (psion)
  224.     to iso8859-1. Only characters > 127 are effected.
  225.   - nfsc.opl: if you want to see the rom and the C drive on the psion,
  226.     change the maxdev% variable in the opl program, and comment in the
  227.     specific dv$ lines.
  228.     nfsc4 users have a dialog for this purpose.
  229.   - The opl program prints a character for each request it receives.
  230.   - If you want to enable the "automatic wakeup on demand" feature, you
  231.     have to turn the switch in the LINK cable and start p3nfsd with the 
  232.     -wakeup option. This option enabled causes a delay of some seconds
  233.     before an error is reported if the psion is not attached.
  234.   - You can specify a UN*X program which is called each time the psion
  235.     is connected or disconnected. (nfsd -connect / -disconnect)
  236.   - ls <mntdir>/debug, SIGUSR1, and the option -v increases the p3nfsd debug
  237.     level (there are 4 levels, from 0 to 3).
  238.  
  239. KNOWN PROBLEMS:
  240.   - If you have a dialog open for nfsc4, the program can't respond to any
  241.     serial line requests.
  242.   - As nfs caches data, you may see an empty main directory even after
  243.     _re_attaching the psion. Just go to your desired directory:
  244.     cd /psion.stand/m/wrd
  245.   - While nfsc.opl is transferring data, please avoid any activity on
  246.     the psion AND SWITCH TO THE NFSC APPLICATION TO GET MORE PRIORITY !!!!
  247.     (especially if writing on ssd), as such activity can lead to malfunc-
  248.     tioning of the hardware flow-control :-(
  249.     The C program (an s3a feature) raises its priority to the maximum.
  250.   - It is not recommended to mount the psion on top of an nfs
  251.     mounted directory (problems with df). Affects mostly diskless clients.
  252.   - setattribute only partially implemented ->
  253.     - tar may report problems after unpacking each file
  254.     - you can't delete read-only files from the unix-side
  255.   - please close all open files before doing a backup, as the files are
  256.     opened exclusively by most programs (not nfsc.opl) and so they can't
  257.     be read by anybody else.
  258.   
  259.  
  260.   - I encountered some problems on HP-UX, with writing files on the psion.
  261.     The problem is that the kernel and each of the biod's are trying to
  262.     send the nfs packets, in order to get a better performance. If the file
  263.     is bigger than 3 times BLOCKSIZE, I receive following blocks:
  264.     1. the last one(!)
  265.     2. the first one
  266.     3. the second one
  267.     Here comes a timeout of about 1 minute, I'd like to know why.
  268.     4. ... (the remaining blocks)
  269.     Since the psion doesn't support writes behind the end of the file, I
  270.     drop blocks not yet written to the psion (with a warning message) after
  271.     a timeout of currently 2 seconds.
  272.     A workaround for this is to kill all biods :-( -> reads from other nfs
  273.     servers becomes possibly slower.
  274.  
  275. PORTING:
  276.   To port p3nfsd to another architecture, take a look at:
  277.  
  278.   mp_serial.c    for the serial drives setting
  279.   mp_mount.c     for the nfs mount (The amd source could help you)
  280.   config.h       for the defaults
  281.   pty.h          for the pseudo tty stuff.
  282.  
  283.   Content of the files (should not have to be changed by a port):
  284.   mp.h:          Various defines
  285.   mp_inode.c:    the inode routines and the read/write cache routines.
  286.   mp_main.c
  287.   mp_mount.c:    nfs mount & rpc service start
  288.   mp_pfs_ops.c:  the nfs routines
  289.   mp_serial.c:   tty settings
  290.   mp_xmit.c      description of protocol used between the psion and the
  291.                  workstation; receive & send routines
  292.   crc.c          crc routines.
  293.   nfs_*:         all generated from nfs.x via rpcgen, withsome of them
  294.                  slightly modified to satiate the compiler warnings
  295.  
  296.   nfsc:
  297.   nfsc.opl       the opl program for the psion (S3a)
  298.   nfsc_s3.opl    the same for the S3
  299.   nfsc4.c        C client (protocol and window routines)
  300.   vt100.c        C client (terminal emulator stuff)
  301.   xymodem.c      C client (X/Y modem support)
  302.  
  303. AT LAST:
  304.   This as a reminder for those who want to check for a newer version of
  305.   the nfsd, but have forgotten the address:
  306.   ftp.uni-erlangen.de:/pub/psion/local
  307.