Update of /cvsroot/alsa/alsa-lib/src/seq
In directory sc8-pr-cvs1:/tmp/cvs-serv3216/seq
Modified Files:
seq.c
Log Message:
more documents as introduction.
Index: seq.c
===
RCS file: /cvsroot/alsa/alsa-lib/src/seq/seq.c,v
retrieving revision 1.85
retrieving revision 1.86
diff -u -r1.85 -r1.86
--- seq.c 27 Aug 2003 13:54:55 - 1.85
+++ seq.c 20 Oct 2003 14:04:53 - 1.86
@@ -30,7 +30,753 @@
/*! \page seq Sequencer interface
-PDescription...
+\section seq_general Genral
+
+The ALSA sequencer interface is designed to deliver the MIDI-like
+events between clients/ports.
+A typical usage is the MIDI patch-bay. A MIDI application can be
+connected arbitrarily from/to the other MIDI clients.
+The routing between clients can be changed dynamically, so the
+application can handle incoming or outgoing MIDI events regardless of
+the devices or the application connections.
+
+The sequencer core stuff only takes care of two things:
+scheduling events and dispatching them to the destination at the
+right time. All processing of MIDI events has to be done within the clients.
+The event can be dispatched immediately without queueing, too.
+The event scheduling can be done either on a MIDI tempo queue or
+on a wallclock-time queue.
+
+\section seq_client Client and Port
+
+A iclient/i is created at each time #snd_seq_open() is called.
+Later on, the attributes of client such as its name string can be changed
+via #snd_seq_set_client_info(). There are helper functions for ease of use,
+e.g. #snd_seq_set_client_name() and #snd_seq_set_client_event_filter().
+A typical code would be like below:
+\code
+// create a new client
+snd_seq_t *open_client()
+{
+snd_seq_t *handle;
+int err;
+err = snd_seq_open(handle, default, SND_SEQ_OPEN_INPUT, 0);
+if (err 0)
+return NULL;
+snd_seq_set_client_name(handle, My Client);
+ return handle;
+}
+\endcode
+
+You'll need to know the id number of the client eventually, for example,
+when accessing to a certain port (see the section \ref seq_subs).
+The client id can be obtained by #snd_seq_client_id() function.
+
+A client can have one or more iports/i to communicate between other
+clients. A port is corresponding to the MIDI port in the case of MIDI device,
+but in general it is nothing but the access point between other clients.
+Each port may have capability flags, which specify the read/write
+accessbility and subscription permissions of the port.
+For creation of a port, call #snd_seq_create_port() \endlink
+with the appropirate port attribute specified in #snd_seq_port_info_t
+reocrd.
+
+For creating a port for the normal use, there is a helper function
+#snd_seq_create_simple_port(). An example with this function is like below.
+\code
+// create a new port; return the port id
+// port will be writable and accept the write-subscription.
+int my_new_port(snd_seq_t *handle)
+{
+ return snd_seq_create_simple_port(handle, my port,
+ SND_SEQ_PORT_CAP_WRITE|SND_SEQ_PORT_CAP_SUBS_WRITE,
+ SND_SEQ_PORT_TYPE_MIDI_GENERIC);
+}
+\endcode
+
+\section seq_memory Memory Pool
+
+Each client owns memory pools on kernel space
+for each input and output events.
+Here, input and output mean
+input (read) from other clients and output (write) to others, respectively.
+Since memory pool of each client is independent from others,
+it avoids such a situation that a client eats the whole events pool
+and interfere other clients' responce.
+
+The all scheduled output events or input events from dispatcher are stored
+on these pools until delivered to other clients or extracted to user space.
+The size of input/output pools can be changed independently.
+The output pool has also a room size, which is used to wake up the
+thread when it falls into sleep in blocking write mode.
+
+Note that ports on the same client share the same memory pool.
+If a port fills the memory pool, another can't use it any more.
+For avoiding this, multiple clients can be used.
+
+For chancing the pool size and the condition, access to #snd_seq_client_pool_t
+record. There are helper functions, #snd_seq_set_client_pool_output(),
+#snd_seq_set_client_pool_output_room() and #snd_seq_set_client_pool_input(),
+for setting the total output-pool size, the output-room size and the input-pool
+size, respectively.
+
+\section seq_subs Subscription
+
+One of the new features in ALSA sequencer system is isubscription/i of ports.
+In general, subscription is a connection between two sequencer ports.
+Even though an event can be delivered to a port without subscription
+using an explicit destination address,
+the subscription mechanism provides us more abstraction.
+
+Suppose a MIDI input device which sends events from a keyboard.
+The port associated with this device has READ capability - which means
+this port is readable
