Skip to content

Commit 6bee9c1

Browse files
mvac7mvac7
committed
HOWTO and README
1 parent f06d716 commit 6bee9c1

File tree

8 files changed

+447
-214
lines changed

8 files changed

+447
-214
lines changed

‎README.md

+32-212
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,8 @@ Programming language: C and Z80 assembler
1111
---
1212
## Description
1313

14-
This project is an opensource library functions for access to internal or external MSX PSG AY-3-8910.
14+
Library functions for access to internal or external MSX PSG AY-3-8910.
1515

16-
Designed for developing MSX applications using Small Device C Compiler (SDCC).
17-
1816
It does not use the BIOS so it can be used to program both ROMs or MSX-DOS executables.
1917

2018
This library is similar to the [PSG AY-3-8910 RT](https://github.com/mvac7/SDCC_AY38910RT_Lib), but instead of writing directly to the registers,
@@ -24,7 +22,7 @@ It is designed to work together with the [PT3player](https://github.com/mvac7/SD
2422

2523
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.
2624

27-
![AY Sound System](https://raw.githubusercontent.com/mvac7/SDCC_AY38910BF_Lib/master/doc/AYlibs.png)
25+
![AY Sound System](docs/AYlibs.png)
2826

2927
It incorporates the SOUND function with the same behavior as the command included in MSX BASIC,
3028
as well as specific functions to modify the different sound parameters of the AY.
@@ -38,7 +36,14 @@ This type uses the values "ON" or "OFF", which equals 1 and 0 respectively.
3836

3937
Include definitions to improve the readability of your programs.
4038

41-
In the source code (\examples), you can find applications for testing and learning purposes.
39+
Use them for developing MSX applications using Small Device C Compiler (SDCC).
40+
41+
This project is an Open Source library.
42+
You can add part or all of this code in your application development or include it in other libraries/engines.
43+
44+
You can access the documentation here with [`How to use the library`](docs/HOWTO.md).
45+
46+
In the source code [`examples/`](examples/), you can find applications for testing and learning purposes.
4247

4348
![TEST AY Lib](https://raw.githubusercontent.com/mvac7/SDCC_AY38910BF_Lib/master/examples/test01_ROM/GFX/TESTAYBF_screenshot.png)
4449

@@ -50,14 +55,14 @@ Enjoy it!
5055

5156
## History of versions
5257

53-
* v0.9b (07 July 2021) First version (Based in AY-3-8910 RT Library)
58+
- v0.9b (07 July 2021) First version (Based in AY-3-8910 RT Library)
5459

5560

5661

5762
## Requirements
5863

59-
* Small Device C Compiler (SDCC) v4.1 > http://sdcc.sourceforge.net/
60-
* Hex2bin v2.5 http://hex2bin.sourceforge.net/
64+
- [Small Device C Compiler (SDCC) v4.1](http://sdcc.sourceforge.net/)
65+
- [Hex2bin v2.5](http://hex2bin.sourceforge.net/)
6166

6267

6368
---
@@ -66,208 +71,23 @@ Enjoy it!
6671

6772
I want to give a special thanks to all those who freely share their knowledge with the MSX developer community.
6873

69-
* Avelino Herrera > [(WEB)](http://msx.avelinoherrera.com)
70-
* Nerlaska > [(Blog)](http://albertodehoyonebot.blogspot.com.es)
71-
* Marq > [(Marq)](http://www.kameli.net/marq/)
72-
* MSXKun/Paxanga soft > [(WEB)](http://paxangasoft.retroinvaders.com/)
73-
* Fubukimaru [(gitHub)](https://github.com/Fubukimaru)
74-
* Andrear > [(Blog)](http://andrear.altervista.org/home/msxsoftware.php)
75-
* Sapphire/Z80ST > [(WEB)](http://z80st.auic.es/)
76-
* Fernando García > [(Curso)](http://www.z80st.es/cursos/bitvision-assembler)
77-
* Ramones > [(MSXblog)](https://www.msxblog.es/tutoriales-de-programacion-en-ensamblador-ramones/) - [(MSXbanzai)](http://msxbanzai.tni.nl/dev/faq.html)
78-
* Eric Boez > [(gitHub)](https://github.com/ericb59)
79-
* MSX Assembly Page > [(WEB)](http://map.grauw.nl/resources/msxbios.php)
80-
* Portar MSX Tech Doc > [(WEB)](https://problemkaputt.de/portar.htm)
81-
* MSX Resource Center [Development Wiki](https://www.msx.org/wiki/#Developing_for_MSX)
82-
* Karoshi MSX Community > [(WEB)](http://karoshi.auic.es/)
83-
* BlueMSX emulator >> [(WEB)](http://www.bluemsx.com/)
84-
* OpenMSX emulator >> [(WEB)](http://openmsx.sourceforge.net/)
85-
* [WebMSX](https://webmsx.org/) emulator by Paulo A. Peccin >> [(gitHub)](https://github.com/ppeccin/webmsx)
86-
* fMSX emulator by Marat Fayzullin [WEB](https://fms.komkon.org/fMSX/)
87-
* Meisei emulator >> ?
88-
89-
90-
<br/>
91-
92-
---
93-
94-
95-
96-
97-
98-
99-
100-
101-
102-
103-
## Definitions
104-
105-
106-
### AY Type
107-
108-
Label | Value
109-
-- | --
110-
AY_INTERNAL | 0
111-
AY_EXTERNAL | 1
112-
113-
114-
### AY Registers
115-
116-
Label | Value | Description
117-
-- | -- | --
118-
AY_ToneA | 0 | Channel A Tone Period (12 bits)
119-
AY_ToneB | 2 | Channel B Tone Period (12 bits)
120-
AY_ToneC | 4 | Channel C Tone Period (12 bits)
121-
AY_Noise | 6 | Noise Period (5 bits)
122-
AY_Mixer | 7 | Mixer
123-
AY_AmpA | 8 | Channel Volume A (4 bits + B5 active Envelope)
124-
AY_AmpB | 9 | Channel Volume B (4 bits + B5 active Envelope)
125-
AY_AmpC | 10 | Channel Volume C (4 bits + B5 active Envelope)
126-
AY_EnvPeriod | 11 | Envelope Period (16 bits)
127-
AY_EnvShape | 13 | Envelope Shape
128-
129-
130-
### Envelope shapes
131-
132-
The header file defines envelope shapes in case you prefer to use it instead
133-
of the numerical form:
134-
135-
Label | Value
136-
-- | --
137-
AY_ENV_LowerBeat | 1
138-
AY_ENV_Upper | 4
139-
AY_ENV_LeftSaw | 8
140-
AY_ENV_LowerTriangle | 10
141-
AY_ENV_LowerHold | 11
142-
AY_ENV_RightSaw | 12
143-
AY_ENV_UpperHold | 13
144-
AY_ENV_UpperTriangle | 14
145-
146-
**Attention!** The LowerBeat shape may be produced with the values: 0, 1, 2, 3 and 9.
147-
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
148-
write the envelop" event. Remember that, every time the register 13 is written, the sound with the assigned shape is started.
149-
150-
The Upper shape may be produced with the values: 4, 5, 6, 7 and 15.
151-
152-
153-
154-
### AY channels
155-
156-
You can use it in the functions: SetTonePeriod, SetVolume and SetChannel
157-
158-
Label | Value
159-
-- | --
160-
AY_Channel_A | 0
161-
AY_Channel_B | 1
162-
AY_Channel_C | 2
163-
164-
165-
166-
## Functions
167-
168-
* **AY_Init**() - Initialize the buffer
169-
* **SOUND**(register, value) - Write into a register of PSG
170-
* **GetSound**(register) - Read PSG register value
171-
* **SetTonePeriod**(channel, period) - Set Tone Period for any channel
172-
* **SetNoisePeriod**(period) - Set Noise Period
173-
* **SetEnvelopePeriod**(period) - Set Envelope Period
174-
* **SetVolume**(channel, volume) - Set volume channel
175-
* **SetChannel**(channel, isTone, isNoise) - Mixer. Enable/disable Tone and Noise channels.
176-
* **SetEnvelope**(shape) - Set envelope type. Plays the sound on channels that have a volume of 16.
177-
* **PlayAY**() - Send data from AYREGS buffer to AY registers. (Execute on each interruption of VBLANK).
178-
179-
180-
181-
## Set Internal or External AY
182-
183-
To indicate in which PSG the sounds are to be played, you have the **AY_TYPE** variable.
184-
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).
185-
186-
```
187-
AY_TYPE = AY_EXTERNAL;
188-
```
189-
190-
**Attention!** When you execute the AY_Init() function, it will be updated to the default value corresponding to the internal AY.
191-
192-
193-
194-
---
195-
196-
197-
## How to use this
198-
199-
coming soon...
200-
201-
202-
203-
204-
---
205-
## Appendices
206-
207-
### AY-3-8910 Register Table
208-
209-
<table>
210-
<tr>
211-
<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>
212-
</tr>
213-
<tr>
214-
<td>R0</td><td rowspan=2>Channel A Tone Period</td><td colspan=8 align=center>8-Bit Fine Tune A</td>
215-
</tr>
216-
<tr>
217-
<td>R1</td><td colspan=4></td><td colspan=4 align=center>4-Bit Coarse Tune A</td>
218-
</tr>
219-
<tr>
220-
<td>R2</td><td rowspan=2>Channel B Tone Period</td><td colspan=8 align=center>8-Bit Fine Tune B</td>
221-
</tr>
222-
<tr>
223-
<td>R3</td><td colspan=4></td><td colspan=4 align=center>4-Bit Coarse Tune B</td>
224-
</tr>
225-
<tr>
226-
<td>R4</td><td rowspan=2>Channel C Tone Period</td><td colspan=8 align=center>8-Bit Fine Tune C</td>
227-
</tr>
228-
<tr>
229-
<td>R5</td><td colspan=4></td><td colspan=4 align=center>4-Bit Coarse Tune C</td>
230-
</tr>
231-
<tr>
232-
<td>R6</td><td>Noise period</td><td colspan=3></td><td colspan=5 align=center>5-Bit Period control</td>
233-
</tr>
234-
<tr>
235-
<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>
236-
<tr>
237-
<td align=center> IOB</td><td align=center>IOA</td><td align=center>C</td>
238-
<td align=center>B</td><td align=center>A</td><td align=center>C</td>
239-
<td align=center>B</td><td align=center>A</td>
240-
</tr>
241-
<tr>
242-
<td>R8</td><td>Channel A Amplitude</td><td colspan=2></td><td align=center>Env</td><td colspan=5 align=center>Amplitude</td>
243-
</tr>
244-
<tr>
245-
<td>R9</td><td>Channel B Amplitude</td><td colspan=2></td><td align=center>Env</td><td colspan=5 align=center>Amplitude</td>
246-
</tr>
247-
<tr>
248-
<td>R10</td><td>Channel C Amplitude</td><td colspan=2></td><td align=center>Env</td><td colspan=5 align=center>Amplitude</td>
249-
</tr>
250-
<tr>
251-
<td>R11</td><td rowspan=2>Envelope Period</td><td colspan=8 align=center>8-Bit Fine Tune Envelope</td>
252-
</tr>
253-
<tr>
254-
<td>R12</td><td colspan=8 align=center>8-Bit Coarse Tune Envelope</td>
255-
</tr>
256-
<tr>
257-
<td>R13</td><td>Envelope Shape/Cycle</td><td colspan=4></td><td>CONT</td><td>ATT</td><td>ALT</td><td>HOLD</td>
258-
</tr>
259-
<tr>
260-
<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>
261-
</tr>
262-
<tr>
263-
<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>
264-
</tr>
265-
</table>
266-
267-
<br/>
268-
269-
---
270-
## References
74+
- Avelino Herrera > [`WEB`](http://msx.avelinoherrera.com/index_es.html)
75+
- Nerlaska > [`Blog`](http://albertodehoyonebot.blogspot.com.es)
76+
- Marq > [`Marq`](http://www.kameli.net/marq/)
77+
- MSXKun/Paxanga soft > [`WEB`](http://paxangasoft.retroinvaders.com/)
78+
- Fubukimaru [`gitHub`](https://github.com/Fubukimaru)
79+
- Andrear > [`Blog`](http://andrear.altervista.org/home/msxsoftware.php)
80+
- Sapphire/Z80ST > [`WEB`](http://z80st.auic.es/)
81+
- Fernando García > [`Video Tutorial`](http://www.z80st.es/cursos/bitvision-assembler)
82+
- Ramones > [`MSXblog`](https://www.msxblog.es/tutoriales-de-programacion-en-ensamblador-ramones/) - [`MSXbanzai`](http://msxbanzai.tni.nl/dev/faq.html)
83+
- Eric Boez > [`gitHub`](https://github.com/ericb59)
84+
- MSX Assembly Page > [`WEB`](http://map.grauw.nl/resources/msxbios.php)
85+
- Portar MSX Tech Doc > [`WEB`](https://problemkaputt.de/portar.htm)
86+
- MSX Resource Center > [`WEB`](http://www.msx.org/)
87+
- Karoshi MSX Community > [`WEB`](http://karoshi.auic.es/)
88+
- BlueMSX emulator >> [`WEB`](http://www.bluemsx.com/)
89+
- OpenMSX emulator >> [`WEB`](http://openmsx.sourceforge.net/)
90+
- [`WebMSX`](https://webmsx.org/) emulator by Paulo A. Peccin >> [`gitHub`](https://github.com/ppeccin/webmsx)
91+
- fMSX emulator by Marat Fayzullin [`WEB`](https://fms.komkon.org/fMSX/)
92+
- Meisei emulator by Hap >> `?`
27193

272-
* [General Instrument AY-3-8910 (wikipedia)](https://en.wikipedia.org/wiki/General_Instrument_AY-3-8910)
273-
* [GI AY-3-8910 Datasheet (PDF)](http://map.grauw.nl/resources/sound/generalinstrument_ay-3-8910.pdf)

‎_Releases/AY38910BF.h

+1
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@
6666
#define AY_Channel_C 2
6767

6868

69+
6970
// AY type
7071
#define AY_INTERNAL 0
7172
#define AY_EXTERNAL 1

‎doc/AYlibs.png ‎docs/AYlibs.png

File renamed without changes.

‎doc/AYlibs.svg ‎docs/AYlibs.svg

File renamed without changes.

0 commit comments

Comments
 (0)