File: README

package info (click to toggle)
alsa-tools 1.0.28-1
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 12,464 kB
  • ctags: 5,787
  • sloc: ansic: 23,609; cpp: 15,057; sh: 12,305; pascal: 1,140; asm: 1,053; xml: 814; makefile: 733; python: 250
file content (432 lines) | stat: -rw-r--r-- 10,318 bytes parent folder | download | duplicates (7)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432

AS10k1 Assembler version A0.99
------------------------------

This is an assembler for the emu10k1 DSP chip present in the creative SB
live, PCI 512, and emu APS sound cards. It is used to make audio effects such 
as a flanger, chorus or reverb.


Author: Daniel Bertrand <d.bertrand@ieee.ca>


This version of the assembler was modified for the ALSA driver by
Jaroslav Kysela <perex@perex.cz>.


Usage: as10k1 <asm file> [bin output file] 
------

Making binary DSP programs:

example, type:

./as10k1 chorus.asm

(it creates chorus.bin)

--
Loading Binary DSP files


<..TODO..>


Description of files included
------------------------------

Chorus.asm	-- chorus effect
Flanger.asm	-- flanger effect
Delay.asm	-- generates Echos, this is _not_ a reverb
eq5.asm		-- A 5 band Equalizer (needs a bit more work)
fir.asm		-- A low pass filter (A demo of a fir filter implementation)
sine.asm	-- A sinewave generator (can be useful for debuging)
vibrato.asm	-- A vibrato effect (or is it a tremolo?)
vol_ctrl.asm	-- provides support for the hardware volume control
emu_constants.asm -- not an effect, just contains handy constants and macros




===============================================================================


Programming Usage:
=================

Assembly Syntax
---------------

Assembly lines generally have four fields seperated by spaces or tabs:


Name_Field   Opcode_field    Operand_Field   Comment_Field
----------   ------------    -------------   -------------
[symbol]      [mnemonic]      [operands]       [text]


With this assembler, each line can have a maximum of 256 characters and each
symbol can be a maximum of 32 characters. Symbols ARE case sensitive, opcodes
ARE NOT.

OPCODES
--------


All instructions require 4 operands, they have the format

	<opcode> R,A,X,Y
	
(note some documentation out there the call the R operand as Z and the A
operand as W).

Here are 16 opcodes.

   0x0 (MACS) : R = A + (X * Y >> 31)   ; saturation
   0x1 (MACS1) : R = A + (-X * Y >> 31)  ; saturation
   0x2 (MACW) : R = A + (X * Y >> 31)   ; wraparound
   0x3 (MACW1) : R = A + (-X * Y >> 31)  ; wraparound
   0x4 (MACINTS) : R = A + X * Y  ; saturation
   0x5 (MACINTW) : R = A + X * Y  ; wraparound (31-bit)
   0x6 (ACC3) : R = A + X + Y  ; saturation
   0x7 (MACMV) : R = A, acc += X * Y >> 31
   0x8 (ANDXOR) : R = (A & X) ^ Y
   0x9 (TSTNEG) : R = (A >= Y) ? X : ~X
   0xa (LIMIT) : R = (A >= Y) ? X : Y
   0xb (LIMIT1): R = (A < Y) ? X : Y
   0xc (LOG) : ...
   0xd (EXP) : ...
   0xe (INTERP) : R = A + (X * (Y - A) >> 31)  ; saturation
   0xf (SKIP) : R,CCR,CC_TEST,COUNT  


Special note on the accumulator: 
mac* instruction with ACCUM as A operand     => uses Most significant 32 bits.
macint* instruction with ACCUM as A operand  => uses Least significant 32 bits.


For more details on the emu10k1 see the dsp.txt file distributed with the
linux driver.



Operands
--------

Operands can be specified as either a symbol or a value. hex values are
prefixed by $, octal by @, and binary by %.

e.g.:

123 decimal value
$123 hex value
@123 octal value
%01101 binary value

The operands for emu10k1 instructions are always addresses of registers, there
are no instruction which take immediate values.

Operands currently support basic arithmetic, It does not support bedmas (or is it bodmas)
so don't try to use (). Infact don't put spaces either (for now, until I fix this).

Summary of assembler directives
-------------------------------

	  NAME "string"			;give a name to the patch

<symbol>  IO				;defines an Input/output pair	
<symbol>  CONTROL <symbol>		;defines a controlable GPR	
<symbol>  DYNamic <number of storage spaces>	;defines a temporary GPR
<symbol>  STAtic <initial value>		;defines a constant GPR /w initial value
<symbol>  EQU <Value equated>		;assembly time constant
<symbol>  CONstant <value>		;defines a read-only GPR	

<symbol>  DELAY  <value>		;defines a Delay line
<symbol>  TABLE  <value>		;defines a lookup table

<symbol>  TREAD  <tram id>,<value>	;defines a tram read 
<symbol>  TWRITE <tram id>,<value>	;defines a tram write


	  INCLUDE <"file name">		;includes an external file

	  FOR <variable>=<start>:<finish> ;Assembly-time 'for' statement
	  ENDFOR			;ends a for loop


<symbol>  MACRO	arg1,arg2,arg3....	;used for define a macro
	  ENDM				;end a macro definition

	  END				;ends the code


Detailed description of directives:
----------------------------------

( <> brackets indicate required fields, [] brackets indicate optional fields)

DYNamic  directive (replaces DS):

Defines a storage space from the gpr pool on the emu10k1. The
assembler maintains a pointer to the gpr registers (starting at $100). The
symbol is assigned the value of the address of the gpr pointer. The pointer is
increment by the number following the dynamic directive.

syntax:
<symbol> dynamic <number of storage spaces

or

<symbol> dyn <number of storage spaces>

--
STAtic directive (replaces DC):

Similar to dynamic, but places an initial value in the memory location.

The values specified are slightly different from operands for instructions. 
The values are 32 bit signed intergers so that a maximum magnitude of 2^31 can
be stored. values can be in signed decimal, unsigned octal, binary and hex, 
and in fractional decimal (values between -1 to 1) for filter coefficients.

A fractional decimal is specified using the '#' prefix and can include an 
exponent. These values should be used with the fractional "mac" instructions.

NEW! fractional numbers are now handle automatically, a value between 1 and 
-1 will be converted into fractional form. The old # form still works though.
(BUG:confusion occurs at 1 and -1 however, should 1 be represented as $1
 or $7ffffff?, currently defaults to $1, so #1 still has some importance)

examples:
	.03412
	123E-3
	#-0.1236

syntax:

<symbol> static <initial value>

or

<symbol> sta <initial value>

--
CONTROL

Control registers are similar to DC, but they also include a min and max value. The control register is used
by a mixer app to change values in a GPR (a volume control, for example). 

syntax:

<symbol> CONTROL <initial value>,<min>,<max>

--
IO

Defines an input and an output register.

<symbol> IO

It defines two register, but they both use the symbol. The assembler handles it automagically
depending on whether you're performing a read (X, Y or Z operand) or a write (R operand) to the GPR.

-
If you insist on having two different symbols for read/write (for readability or whatever), use an EQU, 

i.e.:

IN   IO
OUT  EQU  IN

-
To force a read from the output (for whatever reason) use <symbol>.o (i.e. OUT.o)

Writing to an input is not allowed.
--
CONSTANT

defines a read-only constant GPR

When the assembler encounters a CONSTANT define, it'll try three things. First 
it'll check to see if the defined constant is a hardware constant, if so 
substitutes that instead. Next the assembler check to see if another constant 
has alrady been declared with the same value, if so it'll substitute it. Else
it'll declare a new GPR for holding the value of the constant.  

syntax:

<symbol> constant  <value>

or

<symbol> con  <value>


--

DELAY LINES

Delay lines are defined via three directives:

--
DELAY Directive	

Define Delay, used for allocating an amount of TRAM for a delay line.

<symbol>  DELAY  <value>

The symbol is used to identify this delay line.The value is the amount of TRAM 
allocated, it may be specified as a decimal,hex, octal, binary or time value. 

The time value is prefixed with '&' and represents seconds of time.

e.g.

foo DELAY &100e-3  ;;a 100msec delay line
bar DELAY 1000	;;a 1000 sample delay line

--
TABLE directive

Define lookup Table

same as DELAY but for lookup tables. 

--
TREAD Directive

Define read: used for defining a TRAM read point

<symbol1>  TREAD <symbol2>,<value>

The value represents the read point within the delay line. symbol2 defines 
which delay line this read belongs to.

Symbol1 is a pointer to TRAM data register associated with this TRAM read 
operation. The assembler will create <symbol1>.a which points to the TRAM
address register.

example:

fooread TREAD 100e-3,foo
	macs  fooread.a,one,two,three   ; writes a new tram read address 
	macs  temp,fooread,one,two	; reads the data from the delay line 

--
WRITE Direcive

Define write: same as TREAD but used for writing data to a delay line.
<symbol1>  TWRITE <symbol2>,<value>

--
EQU directive:

Equates a symbol to a be constant which is substituted at assembly time:

syntax:

<symbol> EQU <Value equated>

--
END directive

The END directive should be placed at the end of the assembly source file. If
the END directive is not found, a warning will be generated. All text located
after the END directive is ignored.

Syntax:

[symbol]  END

--
INCLUDE Directive

The include directive is used to include external asm files into the current 
asm file.

Syntax:

	INCLUDE <"file name">

The file name Must be enclosed in "" or '' .

examples:

	include 'qwerty.asm'
	include "foobar.asm"
	

--	

MACRO directive 

Used for defining a macro

Defining Macro:

<symbol> macro arg1,arg2,arg3....
	....
	<opcode>  arg4,arg1,arg2...  ;;for example
	....	
	....
	endm

were the <symbol> used is the nmeumonic representing the macro. 

arg1,arg2,arg3... can be any symbols (auto-defining and local to a macro)
as long as the symbol is not already in use outside the macro (i.e. as 
a DC, DS, etc.).

There's no limit to how many arguments can be used.


Using Macro:

	<macro nmeumonic> arg1,arg2,arg3....

where arg1,arg2,arg3,... are values or symbols.

--
Assembly-time For loop


usage:

	For <symbol>=<start>:<stop>
		...
		...
		macs <symbol>,....
		...
	endfor
	
<start> and <stop> must be integers


--
Handling Skips

the as10k1 assembler handles skips in a special way explained best by an example:

	skip CRR,CRR,CC_test,.foo
	...
	...
	...
.foo	...

the "." tell the assembler that the symbol is for skipping purposes, it will
automatically define a GPR when parsing the skip instruction, and when the second
.foo is encountered it will insert the number of instructions to skip. (the skip
instruction needs a GPR by design, so don't blame me for the half-assness of it). 



Features NOT YET Supported
==========================

any ideas?