linmodem/README.arch

113 lines
3.3 KiB
Plaintext

Linmodem architecture
Copyright (c) 2000 Fabrice Bellard
1) Overview:
-----------
The hardware dependent layer (for example lmreal.c, lmsim.c,
lmsoundcard.c) must call the function
void sm_process(struct sm_state *sm, s16 *output, s16 *input, int nb_samples);
at least every 10 ms. It must supply 'nb_samples' 16 bit input samples
at 8000 Hz. The function sm_process returns the 'output' samples it
has computed. These samples can them be sent to the phone line.
'sm_process' handles the dialing, ring detection and Vxx protocol
initization. Then, each protocol can supply a similar function. For
example, 'v8.c' supplies the function:
int V8_process(V8State *sm, s16 *output, s16 *input, int nb_samples);
It returns the modulation to which the modem must go after the V8
phase.
Note that no threads are used. It implies that each 'xx_process'
function must use an internal state machine. The first parameter
('V8State' here) is usually the structure in which the state is
stored.
2) Timing:
---------
The protocols must use only 'nb_samples' as a timing, not the real
time of the system. It allows to simulate the whole modem without
changing anything.
3) Reentrancy:
-------------
Each protocol must be reentrant, so that multiple modems can be
instanciated at the same time. It is needed for example to do
simulations.
4) Data handling:
----------------
When a protocol gets a bit from the input samples, it should can a function
int get_bit(void *opaque);
provided at its initialization with the opaque parameter 'opaque'. The
same should be done for output with :
void put_bit(void *opaque, int bit);
'sm_process' instanciate each protocol by giving it one of its
standard bit I/O functions. These functions are responsible from
handling the higher level protocol (asynchronous, LAPM, V42bis).
See the file 'serial.c' to see how the data can be handled. V42/V42bis
should be added the same way.
The decoded bytes are put in the FIFO sm->rx_fifo. This fifo is then
return to the modem tty. The inverse is done with sm->tx_fifo.
5) Modem configuration:
----------------------
The configuration parameters are defined in 'lm.c'. See 'struct
LinModemConfig default_lm_config'.
6) Linmodem harware interface:
-----------------------------
See the file lmsoundcard.c which gives an example to interface to a
sound card with the Open Sound System API.
7) Linmodem kernel interface:
----------------------------
The hardware interface to an actual modem is not completely defined
yet. However, it will be very close to the Open Sound System API:
- the write() & read() syscalls write & read 16 bit samples from the
modem.
- An ioctl can select the sampling rate (at least 8000 Hz must be
available).
- an ioctl set/reset the offhook relay.
- an ioctl set/reset the pulse relay.
- an ioctl gives the state of the ring detection. Each time the ring
rings, the event POLLPRI (urgent data) should be set so that the
poll() syscall can handle it.
- an ioctl changes the input & output gains, as the volume for a sound
card.
8) AT command parser:
--------------------
See the file atparse.c: The parser must remain sample. We do not want
to support all the AT commands, but only the minimal subset so that
linux programs can work : 'chat' for PPP, 'mgetty/vgetty' for
voice/data/fax calls, 'sendfax' to send faxes.