Programming Sound Cards

home *** CD-ROM | disk | FTP | other *** search

/ Programming Sound Cards / Programming Sound Cards.iso / sound_30 / mpu401.doc < prev next >

Wrap

Text File | 1995-01-01 | 21.9 KB | 727 lines

The following is a synopsis of the functions contained in the MPU401 Library. Data Structures The event structure: The fundamental data structure in the MPU401 library is that of an MPU event. An event consists of a timing delay byte, a status (opcode) byte and 0 or more data bytes. One or more of the previously defined bytes may be omitted in the MIDI or MPU401 data streams. For example, the opcode byte is omitted if the event is of the same type as the previous event. Some event types omit the initial timing byte. The MPU401 library parses this input and deposits the information in a consistent format for ease of processing. The programmer needn't be concerned with most of the exceptions to the basic data format, the library will handle them at the driver level. the C structure describing an MPU401 event is as follows: struct event { /* lenth of data portion (if any) */ unsigned char dlen; /* opcode or 0 if running status */ unsigned char status; /* timing delay value or 255 if opcode is a MPU message */ unsigned char tbyte; /* SYSTEM EXCLUSIVEs are the only events that will exceed 4 bytes of data, so most events will fit into the "data" member, if SYSTEM EXCLUSIVE data exceeds 4 bytes the dptr member points to a calloc()ed data buffer */ union { unsigned char *dptr; /* data buffer ptr */ unsigned char data[4];/* or data buffer */ } d; struct event *n; /* next event in list */ }; To parse an event: if e.tbyte < 240 { if e.status > 239 event is a MPU MARK (CLOCK, END OF MEASURE etc) MPU401.DOC: Copyright 1988, G.E.S Consulting Page 1 else if e.status == 0 event is same as last MIDI event else [e.status > 0 < 240] event is a MIDI event } else (e.tbyte == 255) event is an MPU Message (Data Request, SYSEX, etc). Commands The following commands return 0 upon success, -1 on MPU error, unless otherwise noted. For more detailed reference, see the technical manual that came with your MPU401. int reset_mpu() Resets the MPU401 to its power up state. NOTE: this function will always return -1 after the MPU has been put into UART mode. int get_version() Gets the internal version and revision data from the MPU401. The version and revision are represented in BCD in the high and low bytes of the return value. The revision level is mapped to the alphbet with 1 == A , 2==B and so on. This command is not supported on MPU401s previous to release 1.2B. Example return: if MPU401 is level 1.5A, get_version returns 0x1501. int uart_mode_on() Puts the MPU401 into dumb uart mode. Use reset_mpu() to return to intellegent mode. The remainder of this manual refers to intellegent mode operations only. initialization switches The following functions alter the default operation of the MPU401. Once called the only way the default conditions can be restored is to reset the MPU via reset_mpu(). When used, these functions are normally called once, at the beginning of the application. MPU401.DOC: Copyright 1988, G.E.S Consulting Page 2 int all_notes_off() Disables the MPU from sending out any ALL NOTES OFF message received from midi in. Also prevents ALL NOTES OFF messages from being send due to the interaction of MIDI In and the channel reference tables when all notes have been turned off. int no_real_time() Prevents the MPU401 from creating REAL TIME messages for the MIDI Out Port (Clock, Start, Stop, Continue). Normaly Midi Clocks are constantly send. int all_thru_off() Modifies the way the midi_thru() (see below) command works. Normaly midi_thru(OFF) only affects unfiltered channels. If all_thru_off() has been called midi_thru(OFF) affects ALL channels. int with_timing_byte_on() Modifies the way the MPU passes data the the host when the MPU is in STOP (not playing or recording) mode. By default, the MPU sends only opcode and data bytes when in STOP mode. If with_timing_byte_on() is called, all events are sent with a leading timing byte, regardless of MPU mode. The MPU401 Driver makes this call during initialization. int mode_messages_on() This function allows MIDI mode messages (OMNI ON, POLY, etc) to be passed to the host. By default these messages are masked. int exclusive_thru_on() Allows SYSTEM EXCLUSIVE messages received at MIDI In to be passed through to Midi Out. Normaly these messages are masked. int common_to_host_on() Allows SYSTEM COMMON messages to be forwarded to the host. Normaly these messages are masked. MPU401.DOC: Copyright 1988, G.E.S Consulting Page 3 int real_time_to_host_on() Allows Midi REAL TIME messages received at Midi In to be passed to the host. Normaly these messages are masked. Channel Reference Table Control For the following commands the mode argument is either ON or OFF (see midi.h). int table_a(mode) Turns Channel Reference Table A On or OFF. int table_b(mode) Turns Channel Reference Table B On or OFF. int table_c(mode) Turns Channel Reference Table C On or OFF. int table_d(mode) Turns Channel Reference Table D On or OFF. int set_channel_reference(unsigned table,unsigned channel) Associates a particular channel to a particular Channel Reference Table. The "table" argument is 0 - 3 for tables 'A' - 'D', the "channel" argument is 0 - 15 for channels 1 - 16, respectively. Clock Control int clock(mode) Selects the clock the MPU401 will use for recording and playback where mode is one of INTERNAL_CLOCK, FSK_CLOCK or MIDI_CLOCK (see midi.h). int set_fsk_resolution(mode) Selects the timebase for the TAPE SYNC clock where "mode" is either FSK_TO_INTERNAL or FSK_TO_MIDI (see midi.h). MPU401.DOC: Copyright 1988, G.E.S Consulting Page 4 int set_timebase(type) Sets the resolution of the internal clock to one of six predefined values. The default is TB_120 or 120 ticks per beat (quarter note) (see midi.h). Metronome Control int set_clocks_per_beep(unsigned clocks) Sets the number of MIDI ticks per metronome beep. The default is 12 or one beep per eighth note. int set_beeps_per_measure(unsigned beeps) Sets the number of beeps (above) per measure. The default is 8. int metronome_on(unsigned accent) Turns on the MPU401 metronome. If "accent" is nonzero, the metronome will sound primary and secondary accents. If the "accent" argument is zero, the metronome will sound only primary accents. int metronome_off() Turns off the metronome. Tempo Control int get_tempo() Returns the current tempo setting of the MPU401. The value is in quarter notes per minute. int set_tempo(unsigned beats_per_minute) Sets the MPU401s tempo to "beats_per_minute" quarter note beats per minute. int set_relative_tempo(unsigned newtemp) Temporarily modifies the MPUs tempo by the ration "newtemp"/64. MPU401.DOC: Copyright 1988, G.E.S Consulting Page 5 Eg. If tempo = 60, the call set_relative_tempo(96) would result in a temporary effective tempo of 90. This command is normaly used with the "Conductor" feature of the MPU401. int reset_relative_tempo() Restores the MPUs tempo to that of the last set_tempo() command. Cancels any relative tempo changes. int set_graduation(unsigned value) Sets the rate of RELATIVE TEMPO (above) change. 0 = immediate, 1 = slowest, 255 = fastest. Data Flow Control int active_tracks(unsigned trackmap) Tells the MPU401 which tracks are to be played on the next PLAY request. Argument trackmap is a bit map of the channels to activate. The bitmap can be constructed by ORing the track defines in midi.h. Eg. active_tracks(TRACK_1|TRACK_8) to play tracks 1 and 8. This command does not put the MPU in PLAY mode it only informs it of what you intend to play. int acceptable_channels(unsigned chanmap) Tells the MPU which channels to recognize at Midi In. By default ALL 16 channels are accepted. Argument chanmap is a bitmap of the 16 possible channels. The bitmap can be constructed by ORing the defines in midi.h. Eg. acceptable_channels(CHANNEL_1|CHANNEL_2) causes the MPU to recognize only channels 1 and 2. All other channels are passed through to Midi Out unprocessed (unless all_thru_off() and midi_thru(OFF) have been called). Switches The "mode" argument is either ON or OFF for the following commands. int bender(mode) Enable/disable continuous controller data sent to host. Default is OFF, data is not sent. MPU401.DOC: Copyright 1988, G.E.S Consulting Page 6 int midi_thru(mode) Enable/disable Midi In being passed through to Midi Out. Default is ON, Midi In -> Midi Out (Makes my pf85 sound real wierd!) int data_in_stop_mode(mode) Enable/Disable events occurring when MPU is in STOP mode being sent to the host. Default is OFF, data is sent only during RECORD mode. int send_measure_end(mode) Enable/Disable MEASURE END MPU Messages. Default is ON, measure end messages are sent to the host. NOTE: the current implementation of the MPU401 library looks for an END OF MEAURE event before completing it's record routine. Therefore this function should be called only with the ON argument or mpu.c should be modified. int conductor(mode) Enable/disable the CONDUCTOR feature of the mpu. Default is OFF, conductor data is not requested. int real_time_affection(mode) Enable/disable MPU401 response to REAL TIME Messages (Start, Stop, Continue) at the MIDI In port. Default is ON the MPU will respond to REAL TIME Messages at MIDI In. int clock_to_host(mode) Enable/disable clock messsages to host. Default is OFF, clock events are not sent. int exclusive_to_host(mode) Enable/disable SYSTEM EXCLUSIVE Messages. Default = OFF, system exclusive messages are filtered by the MPU410 MPU401.DOC: Copyright 1988, G.E.S Consulting Page 7 Counter Control int clear_play_counters() Clears the play counters for all active tracks. Normaly called before a "play from beginning of track" operation. int clear_play_map() Clears the MPU401 play map! int clear_record_counter() Clears the record counter, but never needs to be called as the MPU does this prior to going into RECORD mode anyway. Provided for completeness. int get_play_counter(unsigned track) Returns the value of the play counter for the requested track. Argument "track" is a value between 0 and 7 corresponding to tracks 1- 8. int send_play_counters(unsigned trackmap) Tells the MPU which play counters to send during the next "punch in" operation. Argument "trackmap" is constructed as under "active_tracks()" above. int get_record_counter() Returns the current value of the record counter. IO primitives int mpu_init() Installs the MPU401 driver. Should be one of the first things you do in your program. int mpu_close() UnInstalls the MPU401 driver. Should be the last thing your program does before it exits. If you dont do this your system will crash. MPU401.DOC: Copyright 1988, G.E.S Consulting Page 8 int want_to_send_data(unsigned track, char *data,unsigned len) Send a MIDI message asyncronously to the MPU401. Argument "track" is a value 0 - 7 corresponding to tracks 1 - 8. Buffer "data" contains a valid MIDI message (without leading timing byte). "len" is the count of data bytes in Buffer "data". Should NOT be used on "active" tracks during playback. The MIDI message may not be of the SYSTEM type (use want_to_send_system() below). See demo file notes.c for and example of how this function can be used. int want_to_send_system(char *data,unsigned len) Similar to "want_to_send_data()" above except that the MIDI message argument will contain a SYSTEM class message. struct event *get_event(unsigned char *running,unsigned timeout) Accumulates the next message from the mpu401. Argument "running" is a pointer to a byte sized data space where RUNNING STATUS information will be kept. The space should be initialized to 0 before each "record" or "play" operation. Argument "timeout" is the maximum intercharacter time to wait, in seconds. Returns a pointer to a filled event structure or a null pointer if out of memory or timed out. See data.c demo for an example. Event Allocation int event_list_init(unsigned maxevents) Should be one of the first thing your program does. Creates a pool of event structures for you and the interrupt handler to share. Maxevents is the highest number of events you want in thousands. This is so you can reserve some memory for other things (like forking a shell, see play.c). To use all available memory, just pass a large request like 999 or 9999. Returns the number of events in the free pool. struct event *event_alloc() Grab an event structure from the free pool. MPU401.DOC: Copyright 1988, G.E.S Consulting Page 9 void event_free(struct event *p) Return an event structure to the free pool. long events_available() Returns the number of unallocated events remaining. Queue Manipulation The MPU Driver provided in the MPU401 library has two modes: NORMAL and INTERRUPT mode. In NORMAL mode the driver behaves much the same as any serial communications driver. You send commands and retrieve events via get_event() calls. In INTERRUPT mode, you set up input, and output queues, issue a record or play start command and the driver does the rest. It will satisfy MPU401 requests for track data, and store incomming MIDI data in the queues that have been set up. Your program can go off and do something useful (see play.c) while the driver handles all the nitty gritty stuff. The following functions apply to INTERRUPT MODE only. int que_done() Returns true when the current PLAY or RECORD operation has completed. int set_play_que(int queno,struct event *qp) Instructs the driver to satisfy MPU TRACK DATA requests for track "queno" from the list of events pointed to by "qp". "queno" is 0 - 7 corresponding to tracks 1 - 8. int set_record_que(struct event **qp) Instructs the driver to construct a list of events anchored to *qp where qp is the address of a pointer to an event structure. The driver will allocate event structures as needed and chain them to *qp. (See record.c and play.c) int reset_ques() Decouples and resets the drivers queue pointers. DOES NOT effect any data that may be contained in the queues. The driver simply forgets about them. MPU401.DOC: Copyright 1988, G.E.S Consulting Page 10 int record_start(), play_start() Places driver in INTERRUPT MODE and begins the function named. If play ques have been set up and active_tarcks() called for the corresponding tracks, track data will be played during a RECORD operation. record_stop(), play_stop() Interrupts PLAY or RECORD, returns driver to NORMAL mode. NOTE: record_stop() will take effect at the end of the measure being recorded when the function is called. NORMAL MODE Commands mpu_control(unsigned char command) Provides a NORMAL MODE interface to the PLAY and RECORD functions. The command argument consists of the ORing of values from the following groups (max 1 from each group): START_RECORD, STOP_RECORD Group 1 START_PLAY, STOP_PLAY Group 2 MIDI_START, MIDI_STOP, MIDI_CONTINUE Group 3 When using this mode all MPU requests must be satisfied under your program,s control. get_event should be called in a loop and the opcode byte examined to determine appropriate action. send_message may be used to output events to the MPU401. int send_message(struct event *p) Forward the event pointed to by "p" to the MPU401. p->tbyte is a delay value between 0 and 239 or 255 p->status is 0 (running status [you maintain it] or 0x80 - 0xef or 0xf8 or 0xf9 or 0xfc (when tbyte < 240) or 0xf8 or 0xff if tbyte == 255 p->dlen is length of data p->d.data is data appropriate to p->status int error(char *s) A dummy error reporting routine. ie. printf("%s\n",s); MPU401.DOC: Copyright 1988, G.E.S Consulting Page 11