Using SMP: (SYS$SAMP.LDD), the sound sampling device driver
===========================================================

Files in this zip (TSMP10.ZIP)
------------------------------
README.TXT      This documentation
SYS$SAMP.LDD    The device driver itself
SAMPLER.H       Header file (for C programming)
TSMP.IMG        Example code ready build
TSMP.C          Source of example code (C)
TSMP.OPL        Example code (OPL)
TSMP2.OPL       A second Opl example program

The basic idea of sound samples
-------------------------------
When the microphone is enabled, a "sound value" is provided, by the
hardware, once every 8000th of a second.  This sound value is
actually provided as an ALAW encoded byte (8 bit value).

The PLIB function p_recordsoundw (and related functions) write series
of these sound values (or "sound samples") direct to a nominated
file.  However, using SMP:, you can have these values placed into a
buffer in your dataspace, that you can analyse directly.

You can either analyse these ALAW encoded values directly, or you can
have SMP: return a buffer of decoded values - where the decoded
values are 13 bit numbers in the range -4096 to +4096.

Once you have opened a channel to SMP:, you can use code as simple as
    p_read(pcb,&buf[0],len);
to read 'len' consecutive samples into a buffer.  The largest allowed
value of 'len' is 4000, in which case the data in buf[] represents
half a second of sound.

The supplied test program TSMP
------------------------------
Copy TSMP.IMG into an \IMG\ directory.
Copy SYS$SAMP.LDD into the root directory on the same device.
Go to the RunImg icon, highlight "Tsmp", and press Enter.
Press Enter again to accept the initial suggestion.
You will see a continually refreshed graph of the sound going into
the microphone at that very moment.
Try whistling, talking, or making other noises.
Exit the application from the Shell when you are bored with it.

Note that after you exit TSMP, by default the SMP: device driver is
left loaded in memory (using up around 6k of RAM).  To clean this up,
run the program again, but choose Esc at the initial query alert.

If you make a very short sound, TSMP may fail to pick this up - this
is because TSMP *doesn't* monitor SMP: continuously - it spends a lot
of time drawing its graph instead.  But you could rewrite TSMP in
order to be more responsive.  Ie it could avoid making any display
until the sound reached a higher threshold.  It could improve its
performance even further by reading and analysing the ALAW encoded
values directly, which is a faster service that reading the decoded
values.

Warning: TSMP will keep your S3a switched on!  Be sure to exit it!
Also, while it's running, it will prevent any other access to the
sound system on the S3a - so no alarms will sound, etc.

The C source code and the Opl source code
-----------------------------------------
The code in TSMP.C and TSMP.OPL corresponds in all essential details.
(Except that the C code runs in "compatibility mode".)
For simplicity, I shall just describe the services of SMP: in terms
of the C interface.
(Though I have provided TWO Opl example programs, and only one in C.)

Basic pattern of use of SMP:
----------------------------
Before you can use any of the services of SMP:, you have to open a
channel to it, using p_open.  Eg

    LOCAL_C VOID OpenChannel(VOID)
        {
        INT ret;
    
        ret=p_open(&pcb,"SMP:",-1);
        if (ret)
            Panic(ret,"Failed to open channel to SMP");
        }

This writes back into pcb the "handle" (the "Pointer to the Control
Block") that you use in all subsequent p_read, p_iow, p_close (etc)
calls to SMP:.

Before you can open a channel to SMP:, however, you have to ensure
that the device driver SYS$SAMP.LDD has been loaded into memory.   Eg

    LOCAL_C VOID LoadDriver(VOID)
        {
        INT ret;
        TEXT buf[P_FNAMESIZE];
    
        p_fparse("\\sys$samp.LDD",DatCommandPtr,&buf[0],NULL);
        ret=p_loadldd(&buf[0]);
        if (ret && ret!=E_FILE_EXIST)
            Panic(ret,"Failed to load SYS$SAMP.LDD");
        }

SMP: keeps recording samples internally all the time
----------------------------------------------------
SMP: can have up to four open channels, from four different
applications at the same time.

Whenever there is at least one open channel to SMP:, it keeps
recording sample values internally.  These values then get written
into applications' buffers when requested.

SMP: only keeps half a second's worth of samples, however.

Three modes of using SMP:
-------------------------
In the default mode ("P_SAMPLES_SINCE_LAST"), you ask for a fixed
number of samples, and you at once get given either this number of
samples, or as many as have been collected since the last time you
requested samples (if this is less).

In the mode P_SAMPLES_FROM_LAST, you definitely get given the number
of samples you ask for, starting from the last time you requested
samples, and the call only completes when the required number of
samples is ready.

In the mode P_SAMPLES_FROM_NOW, the same applies, but the samples
only start from "now".

How to change the mode
----------------------
You use the P_FSET function.  Thus
    p_iow3(pcb,P_FSET,mode);

You can also sense the mode, using
    WORD mode;
    p_iow3(pcb,P_FSENSE,&mode);

Reading and "super-reading"
---------------------------
The call
    p_read(pcb,&buf[0],len);
is just equivalent, as always, to
    p_iow4(pcb,P_FREAD,&buf[0],&len);

Here, len is the number of WORDs of data in buf[].

If you prefer, you can use P_FRSUPER instead of P_FREAD, to read a
number of BYTEs of ALAW encoded data - as discussed earlier.  In this
case, there is no utility function p_read - you have to use the p_iow
(or p_ioc etc) call.

In either P_FREAD or P_FRSUPER, the number of samples actually
delivered is written back to the 'len' variable.

Note that only a single P_FREAD or P_FRSUPER per open channel should
be pending at any one time.

Technical note
--------------
The "ALAW encoded data" provided by P_FRSUPER isn't exactly the same
as provided by the raw CODEC hardware.  The value is inverted and
then "magic xor-red" (to XOR all the even bits), before being
returned to the application.  This means that a louder sound will
give rise to a larger value.

(In contrast, the bytes written to file by services such as
p_recordsoundw are *exactly* as provided by the CODEC.)

Synchronous and asynchronous calls
----------------------------------
Like all device drivers, SMP: supports asynchronous versions of its
services as well as synchronous ones.  And you can P_FCANCEL an
outstanding asynchronous request.

Special utility conversion services
-----------------------------------
SMP: also provides a couple of conversion services, to convert a
buffer of WORDs of decoded data into another buffer of BYTEs of ALAW
encoded data, and vice versa.  These services both use the P_CONVERT
struct, defined in the header file SAMPLER.H:

    typedef struct /* Conversion structure */
        {
        VOID *Source;
        VOID *Destination;
        } P_CONVERT;

For example,

    BYTE aLaw[4];
    WORD Data[4];
    P_CONVERT Conversion;

    Len=4;
    Conversion.Source=&Data[0];
    Conversion.Destination=&aLaw[0];
    p_iow4(pcb,P_FCONVERT_TO,&Conversion,&Len);
    Conversion.Source=&aLaw[0];
    Conversion.Destination=&Data[0];
    p_iow4(pcb,P_FCONVERT_FROM,&Conversion,&Len);

Values of some #define's (for Opl programmers)
----------------------------------------------
#define P_FREAD   1
#define P_FCANCEL 4
#define P_FSET    7
#define P_FSENSE  8
#define P_FRSUPER 13

An example program using "super-reading"
----------------------------------------
Have a look at TSMP2.OPL.  Try to figure out what happens when you
run it, and then run it and see if you were right.

Some of the limitations in the performance in TSMP2.OPL are due to
time wasted scanning the buffer for large values.  This time could be
cut down by programming in C, or by creating some machine code and
accessing that using USR.

Disclaimer
----------
Psion will not be held responsible for any loss of data as a result
of use of SYS$SAMP.LDD, which is still to an extent in an experimental
phase.

SYS$SAMP.LDD is not an official Psion product.

It has not yet been exhaustively tested, and cannot be relied upon eg
not to reset your S3a occasionally.

Distribution
------------
You can freely distribute the file TSMP10.ZIP, but all the files in
it should be kept together.

These notes prepared
--------------------
By David Wood, Psion Product Development, 24th March 1994.
Revised, 6th April 1994 (TSMP2.OPL added.)
All comments, bug reports etc welcome by EMAIL (eg CiX) ONLY.