Skip to content

Commit f2d7421

Browse files
mvac7mvac7
committed
Short version #1 
1 parent d2e3d46 commit f2d7421

File tree

7 files changed

+673
-6
lines changed

7 files changed

+673
-6
lines changed

‎README.md

+13-6
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ it does so to a buffer that should be dumped to the AY in each VBLANK frame.
2222

2323
It is designed to work together with the PT3player and/or ayFXplayer libraries, but you can also use it for your own or third-party player.
2424

25+
In this same repository you will find a **short version** [(AY38910BF_S)](https://github.com/mvac7/SDCC_AY38910BF_Lib/tree/main/Short) with the essentials to work with player libraries.
26+
2527
![AY Sound System](https://raw.githubusercontent.com/mvac7/SDCC_AY38910BF_Lib/master/doc/AYlibs.png)
2628

2729
It incorporates the SOUND function with the same behavior as the command included in MSX BASIC,
@@ -45,21 +47,21 @@ This library is part of the [MSX fR3eL Project](https://github.com/mvac7/SDCC_MS
4547
Enjoy it!
4648

4749

48-
---
50+
4951
## History of versions
5052

5153
* v0.9b (07 July 2021) First version (Based in AY-3-8910 RT Library)
5254

5355

54-
---
56+
5557
## Requirements
5658

5759
* Small Device C Compiler (SDCC) v4.1 > http://sdcc.sourceforge.net/
5860
* Hex2bin v2.5 http://hex2bin.sourceforge.net/
5961

6062

6163

62-
---
64+
6365
## Definitions
6466

6567

@@ -122,7 +124,7 @@ AY_Channel_B | 1
122124
AY_Channel_C | 2
123125

124126

125-
---
127+
126128
## Functions
127129

128130
* **AY_Init**() - Initialize the buffer
@@ -137,7 +139,7 @@ AY_Channel_C | 2
137139
* **PlayAY**() - Send data from AYREGS buffer to AY registers. (Execute on each interruption of VBLANK).
138140

139141

140-
---
142+
141143
## Set Internal or External AY
142144

143145
To indicate in which PSG the sounds are to be played, you have the **AY_TYPE** variable.
@@ -151,6 +153,9 @@ To select an external AY (ports 10h to 12h), like the one included in the MegaFl
151153

152154

153155

156+
---
157+
158+
154159
## How to use this
155160

156161
coming soon...
@@ -159,6 +164,7 @@ coming soon...
159164

160165

161166
---
167+
162168
## AY-3-8910 Register Table
163169

164170
<table>
@@ -221,6 +227,7 @@ coming soon...
221227

222228

223229
---
230+
224231
## Acknowledgments
225232

226233
I want to give a special thanks to all those who freely share their knowledge with the MSX developer community.
@@ -237,7 +244,7 @@ I want to give a special thanks to all those who freely share their knowledge wi
237244
* Eric Boez > [(gitHub)](https://github.com/ericb59)
238245
* MSX Assembly Page > [(WEB)](http://map.grauw.nl/resources/msxbios.php)
239246
* Portar MSX Tech Doc > [(WEB)](https://problemkaputt.de/portar.htm)
240-
* MSX Resource Center > [(WEB)](http://www.msx.org/)
247+
* MSX Resource Center [Development Wiki](https://www.msx.org/wiki/#Developing_for_MSX)
241248
* Karoshi MSX Community > [(WEB)](http://karoshi.auic.es/)
242249
* BlueMSX emulator >> [(WEB)](http://www.bluemsx.com/)
243250
* OpenMSX emulator >> [(WEB)](http://openmsx.sourceforge.net/)

‎Short/README.md

+240
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# PSG AY-3-8910 BF Short MSX SDCC Library (fR3eL Project)
2+
3+
```
4+
Author: mvac7
5+
Architecture: MSX
6+
Format: C Object (SDCC .rel)
7+
Programming language: C and Z80 assembler
8+
```
9+
10+
11+
---
12+
13+
## Description
14+
15+
This project is an opensource library functions for access to internal or external MSX PSG AY-3-8910.
16+
17+
Designed for developing MSX applications using Small Device C Compiler (SDCC).
18+
19+
It does not use the BIOS so it can be used to program both ROMs or MSX-DOS executables.
20+
21+
This library is a Short version of the AY38910BF where the definitions and functions necessary to work with player libraries have been left.
22+
It is lighter, leaving room for development.
23+
24+
Provides a record buffer that must be dumped in each VBLANK frame to the AY-3-8910 (internal or external) using the PlayAY function.
25+
26+
It is designed to work together with the PT3player and/or ayFXplayer libraries, but you can also use it for your own or third-party player.
27+
28+
![AY Sound System](https://raw.githubusercontent.com/mvac7/SDCC_AY38910BF_Lib/master/doc/AYlibs.png)
29+
30+
Controls the I/O bits of register 7 (Mixer), of the internal AY.
31+
32+
It allows to use the internal PSG of the MSX or an external one (like the one incorporated in the MEGAFLASHROM SCC+ or the Flashjacks).
33+
34+
In the header file there is a definition of SWITCHER type, needed for the functions.
35+
This type uses the values "ON" or "OFF", which equals 1 and 0 respectively.
36+
37+
Include definitions to improve the readability of your programs.
38+
39+
This library is part of the [MSX fR3eL Project](https://github.com/mvac7/SDCC_MSX_fR3eL).
40+
41+
Enjoy it!
42+
43+
44+
45+
## History of versions
46+
47+
* v0.9b (16 July 2021) First version (Short version from AY38910BF Library)
48+
49+
50+
51+
## Requirements
52+
53+
* Small Device C Compiler (SDCC) v4.1 > http://sdcc.sourceforge.net/
54+
* Hex2bin v2.5 http://hex2bin.sourceforge.net/
55+
56+
57+
58+
## Definitions
59+
60+
61+
### AY Type
62+
63+
Label | Value
64+
-- | --
65+
AY_INTERNAL | 0
66+
AY_EXTERNAL | 1
67+
68+
69+
### AY Registers
70+
71+
Label | Value | Description
72+
-- | -- | --
73+
AY_ToneA | 0 | Channel A Tone Period (12 bits)
74+
AY_ToneB | 2 | Channel B Tone Period (12 bits)
75+
AY_ToneC | 4 | Channel C Tone Period (12 bits)
76+
AY_Noise | 6 | Noise Period (5 bits)
77+
AY_Mixer | 7 | Mixer
78+
AY_AmpA | 8 | Channel Volume A (4 bits + B5 active Envelope)
79+
AY_AmpB | 9 | Channel Volume B (4 bits + B5 active Envelope)
80+
AY_AmpC | 10 | Channel Volume C (4 bits + B5 active Envelope)
81+
AY_EnvPeriod | 11 | Envelope Period (16 bits)
82+
AY_EnvShape | 13 | Envelope Shape
83+
84+
85+
### Envelope shapes
86+
87+
The header file defines envelope shapes in case you prefer to use it instead
88+
of the numerical form:
89+
90+
Label | Value
91+
-- | --
92+
AY_ENV_LowerBeat | 1
93+
AY_ENV_Upper | 4
94+
AY_ENV_LeftSaw | 8
95+
AY_ENV_LowerTriangle | 10
96+
AY_ENV_LowerHold | 11
97+
AY_ENV_RightSaw | 12
98+
AY_ENV_UpperHold | 13
99+
AY_ENV_UpperTriangle | 14
100+
101+
**Attention!** The LowerBeat shape may be produced with the values: 0, 1, 2, 3 and 9.
102+
The value 1 has been assigned to *LowerBeat* as 0 can be useful in case you need to control when the envelope is triggered. In this case 0 can act as a "don't
103+
write the envelop" event. Remember that, every time the register 13 is written, the sound with the assigned shape is started.
104+
105+
The Upper shape may be produced with the values: 4, 5, 6, 7 and 15.
106+
107+
108+
109+
### AY channels
110+
111+
You can use it in the functions: SetTonePeriod, SetVolume and SetChannel
112+
113+
Label | Value
114+
-- | --
115+
AY_Channel_A | 0
116+
AY_Channel_B | 1
117+
AY_Channel_C | 2
118+
119+
120+
121+
## Functions
122+
123+
* **AY_Init**() - Initialize the buffer
124+
* **PlayAY**() - Send data from AYREGS buffer to AY registers. (Execute on each interruption of VBLANK).
125+
126+
127+
128+
## Set Internal or External AY
129+
130+
To indicate in which PSG the sounds are to be played, you have the **AY_TYPE** variable.
131+
To select an external AY (ports 10h to 12h), like the one included in the MegaFlashROM SCC+, Flashjacks or other, you have to set the variable to 1 (or AY_EXTERNAL).
132+
133+
```
134+
AY_TYPE = AY_EXTERNAL;
135+
```
136+
137+
**Attention!** When you execute the AY_Init() function, it will be updated to the default value corresponding to the internal AY.
138+
139+
140+
141+
## How to use this
142+
143+
coming soon...
144+
145+
146+
147+
148+
149+
## AY-3-8910 Register Table
150+
151+
<table>
152+
<tr>
153+
<th colspan=2>Register\bit</th><th width=50>B7</th><th width=50>B6</th><th width=50>B5</th><th width=50>B4</th><th width=50>B3</th><th width=50>B2</th><th width=50>B1</th><th width=50>B0</th>
154+
</tr>
155+
<tr>
156+
<td>R0</td><td rowspan=2>Channel A Tone Period</td><td colspan=8 align=center>8-Bit Fine Tune A</td>
157+
</tr>
158+
<tr>
159+
<td>R1</td><td colspan=4></td><td colspan=4 align=center>4-Bit Coarse Tune A</td>
160+
</tr>
161+
<tr>
162+
<td>R2</td><td rowspan=2>Channel B Tone Period</td><td colspan=8 align=center>8-Bit Fine Tune B</td>
163+
</tr>
164+
<tr>
165+
<td>R3</td><td colspan=4></td><td colspan=4 align=center>4-Bit Coarse Tune B</td>
166+
</tr>
167+
<tr>
168+
<td>R4</td><td rowspan=2>Channel C Tone Period</td><td colspan=8 align=center>8-Bit Fine Tune C</td>
169+
</tr>
170+
<tr>
171+
<td>R5</td><td colspan=4></td><td colspan=4 align=center>4-Bit Coarse Tune C</td>
172+
</tr>
173+
<tr>
174+
<td>R6</td><td>Noise period</td><td colspan=3></td><td colspan=5 align=center>5-Bit Period control</td>
175+
</tr>
176+
<tr>
177+
<td rowspan=2>R7</td><td rowspan=2>Enable (bit 0=on, 1=off)</td><td colspan=2 align=center>IN/OUT</td><td colspan=3 align=center>Noise</td><td colspan=3 align=center>Tone</td></tr>
178+
<tr>
179+
<td align=center> IOB</td><td align=center>IOA</td><td align=center>C</td>
180+
<td align=center>B</td><td align=center>A</td><td align=center>C</td>
181+
<td align=center>B</td><td align=center>A</td>
182+
</tr>
183+
<tr>
184+
<td>R8</td><td>Channel A Amplitude</td><td colspan=2></td><td align=center>Env</td><td colspan=5 align=center>Amplitude</td>
185+
</tr>
186+
<tr>
187+
<td>R9</td><td>Channel B Amplitude</td><td colspan=2></td><td align=center>Env</td><td colspan=5 align=center>Amplitude</td>
188+
</tr>
189+
<tr>
190+
<td>R10</td><td>Channel C Amplitude</td><td colspan=2></td><td align=center>Env</td><td colspan=5 align=center>Amplitude</td>
191+
</tr>
192+
<tr>
193+
<td>R11</td><td rowspan=2>Envelope Period</td><td colspan=8 align=center>8-Bit Fine Tune Envelope</td>
194+
</tr>
195+
<tr>
196+
<td>R12</td><td colspan=8 align=center>8-Bit Coarse Tune Envelope</td>
197+
</tr>
198+
<tr>
199+
<td>R13</td><td>Envelope Shape/Cycle</td><td colspan=4></td><td>CONT</td><td>ATT</td><td>ALT</td><td>HOLD</td>
200+
</tr>
201+
<tr>
202+
<td>R14</td><td>I/O Port A Data Store</td><td colspan=8 align=center>8-Bit Parallel I/O on Port A</td>
203+
</tr>
204+
<tr>
205+
<td>R15</td><td>I/O Port B Data Store</td><td colspan=8 align=center>8-Bit Parallel I/O on Port B</td>
206+
</tr>
207+
</table>
208+
209+
210+
---
211+
212+
## Acknowledgments
213+
214+
I want to give a special thanks to all those who freely share their knowledge with the MSX developer community.
215+
216+
* Avelino Herrera > [(WEB)](http://msx.avelinoherrera.com)
217+
* Nerlaska > [(Blog)](http://albertodehoyonebot.blogspot.com.es)
218+
* Marq > [(Marq)](http://www.kameli.net/marq/)
219+
* MSXKun/Paxanga soft > [(WEB)](http://paxangasoft.retroinvaders.com/)
220+
* Fubukimaru [(gitHub)](https://github.com/Fubukimaru)
221+
* Andrear > [(Blog)](http://andrear.altervista.org/home/msxsoftware.php)
222+
* Sapphire/Z80ST > [(WEB)](http://z80st.auic.es/)
223+
* Fernando García > [(Curso)](http://www.z80st.es/cursos/bitvision-assembler)
224+
* Ramones > [(MSXblog)](https://www.msxblog.es/tutoriales-de-programacion-en-ensamblador-ramones/) - [(MSXbanzai)](http://msxbanzai.tni.nl/dev/faq.html)
225+
* Eric Boez > [(gitHub)](https://github.com/ericb59)
226+
* MSX Assembly Page > [(WEB)](http://map.grauw.nl/resources/msxbios.php)
227+
* Portar MSX Tech Doc > [(WEB)](https://problemkaputt.de/portar.htm)
228+
* MSX Resource Center [Development Wiki](https://www.msx.org/wiki/#Developing_for_MSX)
229+
* Karoshi MSX Community > [(WEB)](http://karoshi.auic.es/)
230+
* BlueMSX emulator >> [(WEB)](http://www.bluemsx.com/)
231+
* OpenMSX emulator >> [(WEB)](http://openmsx.sourceforge.net/)
232+
* Meisei emulator >> ?
233+
234+
235+
---
236+
237+
## References
238+
239+
* [General Instrument AY-3-8910 (wikipedia)](https://en.wikipedia.org/wiki/General_Instrument_AY-3-8910)
240+
* [GI AY-3-8910 Datasheet (PDF)](http://map.grauw.nl/resources/sound/generalinstrument_ay-3-8910.pdf)

‎Short/sources/MAKEFILE.BAT

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
@echo off
2+
if exist build\ goto NEXTSTEP1
3+
echo MAKEDIR build
4+
md build
5+
:NEXTSTEP1
6+
echo Compiling Object
7+
sdcc -mz80 -c -o build\ src\AY38910BF_S.c
8+
pause

0 commit comments

Comments
 (0)