Using the library
Including in your source
To be able to use the library in your software, you need to download the include file to your project directory and include it in your project source file like so:
#include "bell.inc"
This will include a bunch of routines, some that Bell needs, some that you can call. This means that you shouldn't include Bell at the top of your program like you do with an equates include, because that would execute Bell code before your code. Preferably include it at the end of your program, but before your program data, because Bell has mostly code that needs to be executed, and you don't want to put that after the executable code limit.
Settings
Once you have included the library in your project, you'll want to change some settings in bell.inc. Open it up in your editor and walk through the settings described there. Make sure you have changed the program identification string to the name (and version number) of your program and that you have commented the functionality defines that you don't want. You'll be wasting precious bytes on your calculator otherwise.
Routines
The routines that Bell makes available for you to use after inclusion are the following:
- bell_connect
- Waits untill a connected calculator runs a Bell-compatible program. After that, it checks to see if both calculators are running the same program. If so, it returns at approximately the same time on both calculators with the z-flag set. Incompatible program types or a user pressing [Clear] while waiting for an opponent returns nz. You need to run this routine at least once before you can use the swap routines, because this routine initializes the unique calculator IDs.
- bell_sync
- Waits for another calculator to run the same routine, and returns at approximately the same time on both calculators. Returns z on proper synchronize, nz if the user pressed [Clear] while waiting for the other calculator, and the calculator ID in a. bell_connect uses this routine for the initial synchronization.
- bell_sendByte
- Sends the value in a through the link port. If timeouts aren't disabled, it will return nz on a timeout or z when the byte is transferred properly. Otherwise it will return z or loop indefinately.
- bell_recvByte
- Receives a byte from the link port in register a. If timeouts aren't disabled, it will return nz on a timeout or z when the byte is received properly. Otherwise it will return z or loop indefinately.
- bell_swapByte
- Swaps the byte in register a with the connected calculator; the received byte is also returned in a. If timeouts aren't disabled, it will return nz on a timeout or z when the byte is swapped properly. Otherwise it will return z or loop indefinately. This routine requires the calculator IDs to have been set, so you need to have called bell_connect before you can use this routine.
- bell_sendBlock
- Send a block of bytes through the link port. Expects hl to be a pointer to the start of the block of data to be sent and b to be the number of bytes you want to send. If timeouts aren't disabled, it will return nz on a timeout or z when the block is sent properly. Otherwise it will return z or loop indefinately. Maximum block size: 255 bytes.
- bell_recvBlock
- Receive a block of bytes from the link port. Expects hl to be a pointer to a buffer where the received data will be stored. You have to make sure you don't send more bytes than the size of the buffer, because the routine will not handle buffer overflows. If timeouts aren't disabled, it will return nz on a timeout or z when the block is received properly. Otherwise it will return z or loop indefinately. Maximum block size: 255 bytes.
- bell_swapBlock
- Swaps a block of data with the other calc. Expects hl to be a pointer to the start of the block of data to be sent, de to be a pointer to the start of a buffer where the received data will be stored and b to be the number of bytes to be swapped. The latter should be the same on both calculators, otherwise one of them will time out. hl and de can point to the same location in memory, in which case the buffer will literally be swapped. If timeouts aren't disabled, it will return nz on a timeout or z when the block is swapped properly. Otherwise it will return z or loop indefinately. This routine requires the calculator IDs to have been set, so you need to have called bell_connect before you can use this routine. Maximum block size: 255 bytes.
- bell_sendLargeBlock
- Send a block of bytes through the link port. Expects hl to be a pointer to the start of the block of data to be sent and bc to be the number of bytes you want to send. If timeouts aren't disabled, it will return nz on a timeout or z when the block is sent properly. Otherwise it will return z or loop indefinately. Maximum block size: 65535 bytes.
- bell_recvLargeBlock
- Receive a block of bytes from the link port. Expects hl to be a pointer to a buffer where the received data will be stored. You have to make sure you don't send more bytes than the size of the buffer, because the routine will not handle buffer overflows. If timeouts aren't disabled, it will return nz on a timeout or z when the block is received properly. Otherwise it will return z or loop indefinately. Maximum block size: 65535 bytes.
- bell_swapLargeBlock
- Swaps a block of data with the other calc. Expects hl to be a pointer to the start of the block of data to be sent, de to be a pointer to the start of a buffer where the received data will be stored and bc to be the number of bytes to be swapped. The latter should be the same on both calculators, otherwise one of them will time out. hl and de can point to the same location in memory, in which case the buffer will literally be swapped. If timeouts aren't disabled, it will return nz on a timeout or z when the block is swapped properly. Otherwise it will return z or loop indefinately. This routine requires the calculator IDs to have been set, so you need to have called bell_connect before you can use this routine. Maximum block size: 65535 bytes.
- bell_sendString
- Send a zero terminated string through the link port. Expects hl to be a pointer to the start of the string to be sent. If timeouts aren't disabled, it will return nz on a timeout or z when the string is sent properly. Otherwise it will return z or loop indefinately.
- bell_recvString
- Receive a zero terminated string from the link port. Expects hl to be a pointer to the start of a buffer to store the received string. You have to make sure you don't send more bytes than the size of the buffer, because the routine will not handle buffer overflows. If timeouts aren't disabled, it will return nz on a timeout or z when the string is received properly. Otherwise it will return z or loop indefinately.
- bell_swapString
- Swaps a zero terminated string with the other calc. Expects hl to be a pointer to the start of the string to be sent, and de to be a pointer to the start of a buffer to store the received string. hl and de can not point to the same location. If timeouts aren't disabled, it will return nz on a timeout or z when the strings are swapped properly. Otherwise it will return z or loop indefinately. This routine requires the calculator IDs to have been set, so you need to have called bell_connect before you can use this routine.