Link Cable Library (libcomb): Difference between revisions
| Revision as of 02:47, 23 October 2026 RemmyLee (Formats: Sony paragraph voice; HMD, RSD extended files, full BS code book; sprite editor formats) | Revision as of 02:58, 23 October 2026 RemmyLee (Run-time library pages: 20 libraries from the Library Overview and Reference 4.4) | ||
| Line 1: | Line 1: | ||
| + | --- | ||
| + | title: Link Cable Library (libcomb) | ||
| + | type: component | ||
| + | summary: Provides functions for connecting two PlayStation units with a link cable. | ||
| + | category: Libraries | ||
| + | info: Library = libcomb.lib | ||
| + | info: Header File = libcomb.h | ||
| + | --- | ||
| + | |||
| + | ## Overview | ||
| + | |||
| + | The Link Cable Library (libcomb) connects PlayStation units with a link cable. Many games use the link cable, and combat games in particular. Communication is performed by read() and write(). Both support an asynchronous mode, in which an event occurs when the processing is complete, and a synchronous mode, in which the function returns when the communication is complete.[^o14-3] | ||
| + | |||
| + | The communication method is asynchronous serial communication. The maximum rate is 2073600 bps, and _comb_control() changes the rate.[^o14-3] | ||
| + | |||
| + | A program that uses libcomb links with libcomb.lib and includes libcomb.h.[^o14-3] | ||
| + | |||
| + | ## Link Cable Driver | ||
| + | |||
| + | libcomb consists of the link cable driver and the link cable BIOS. The driver lets the standard C input and output functions use the link cable. AddCOMB() installs it and DelCOMB() removes it, and opening the sio device without the driver is an error. The driver has the following properties:[^o14-3] | ||
| + | |||
| + | Table: Link cable driver | ||
| + | |||
| + | | Item | Contents | | ||
| + | | --- | --- | | ||
| + | | Device name | sio | | ||
| + | | Block size | 1, 2, 4 or 8 bytes. Asynchronous write is in 1-byte units. | | ||
| + | | Asynchronous mode | Set by the O_NOWAIT macro on opening | | ||
| + | |||
| + | The driver raises the following events. EvSpIOEW and EvSpIOER follow asynchronous requests, and EvSpERROR occurs in both synchronous and asynchronous reading:[^o14-3] | ||
| + | |||
| + | Table: Link cable events | ||
| + | |||
| + | | Cause descriptor | Event type | Contents | | ||
| + | | --- | --- | --- | | ||
| + | | HwSIO | EvSpIOEW | Completion of asynchronous writing | | ||
| + | | HwSIO | EvSpIOER | Completion of asynchronous reading | | ||
| + | | HwSIO | EvSpERROR | Read error | | ||
| + | | HwSIO | EvSpTIMOUT | Timeout in synchronous reading or writing | | ||
| + | |||
| + | ## Synchronous Input and Output | ||
| + | |||
| + | During a synchronous read or write the driver loops on the status of the serial controller and calls the wait callback in each pass. _comb_control(4, 0, func) registers func() as the wait callback and _comb_control(4, 0, NULL) cancels it, and no callback is registered by default.[^o14-4] | ||
| + | |||
| + | A synchronous read ends when the requested number of characters has arrived. It also ends on a parity, overrun or framing error, or when the wait callback returns the prescribed value, and in every case it returns the number of characters received. A synchronous write ends when the characters have been sent or when the wait callback returns the prescribed value.[^o14-4] | ||
| + | |||
| + | Most libcomb functions never enter a critical section, so they can be called inside an event handler. The library assumes a single thread, however, and its operation is not guaranteed under thread control of the program's own.[^o14-4] | ||
| + | |||
| + | The PlayStation has an 8-byte receive buffer, and the asynchronous read can interrupt after 1, 2, 4 or 8 bytes. This unit number of characters also sets the DSR and DTR handshake in synchronous communication. For an asynchronous write it must be 1, since an interrupt is expected for each byte sent.[^o14-4] | ||
| + | |||
| + | After an overrun, parity or framing error in asynchronous operation, _comb_control(2, 3, 0) cancels the asynchronous read, and the next EvSpERROR event follows. An event handler does only short work such as setting a flag, and the main process performs the error processing.[^o14-4] | ||
| + | |||
| + | ## Link Cable BIOS | ||
| + | |||
| + | The link cable BIOS gives finer control of the driver than the standard C functions. Its interface function is _comb_control(cmd, arg, param). The BIOS works without the driver installed. Its commands are the following:[^o14-4][^o14-5] | ||
| + | |||
| + | Table: _comb_control() commands | ||
| + | |||
| + | | cmd | arg | Function | | ||
| + | | --- | --- | --- | | ||
| + | | 0 | 0 | Return the serial controller status | | ||
| + | | 0 | 1 | Return the control line status | | ||
| + | | 0 | 2 | Return the communication mode | | ||
| + | | 0 | 3 | Return the communication rate in bps | | ||
| + | | 0 | 4 | Return the unit number of characters for receiving | | ||
| + | | 0 | 5 | Return the bytes left in the asynchronous write (param 0) or read (param 1) | | ||
| + | | 0 | 6 | Return 1 if an asynchronous write (param 0) or read (param 1) is registered | | ||
| + | | 1 | 1 | Set the control line status to param | | ||
| + | | 1 | 3 | Set the communication rate to param bps | | ||
| + | | 1 | 4 | Set the unit number of characters for receiving to param | | ||
| + | | 2 | 0 | Reset the serial controller, keeping the status, mode and speed | | ||
| + | | 2 | 1 | Clear the driver status error bits and signal the end of interrupt processing | | ||
| + | | 2 | 2 | Cancel the asynchronous write | | ||
| + | | 2 | 3 | Cancel the asynchronous read | | ||
| + | | 3 | 0 | Set RTS to param | | ||
| + | | 4 | 0 | Register param as the wait callback and return the previous pointer | | ||
| + | |||
| + | The status words returned by the BIOS have the following bits:[^o14-6] | ||
| + | |||
| + | Table: Driver status | ||
| + | |||
| + | | Bit | Contents | | ||
| + | | --- | --- | | ||
| + | | 9 | Interrupt is on | | ||
| + | | 8 | CTS is on | | ||
| + | | 7 | DSR is on | | ||
| + | | 5 | Frame error occurred | | ||
| + | | 4 | Overrun error occurred | | ||
| + | | 3 | Parity error occurred | | ||
| + | | 2 | No sending data | | ||
| + | | 1 | Received data can be read | | ||
| + | | 0 | Sending data can be written | | ||
| + | |||
| + | In the control line status, bit 1 is RTS and bit 0 is DTR. In the communication mode, bits 7 and 6 give the stop bit length (01 for 1, 10 for 1.5 and 11 for 2), bit 5 the odd or even parity, bit 4 the parity enable and bits 3 and 2 the character length from 5 to 8 bits.[^o14-6] | ||
| + | |||
| + | ## Serial Controller | ||
| + | |||
| + | The link cable connector is driven by a serial controller for asynchronous communication. It has a 1-byte transmission buffer and an 8-byte receive buffer. Its two pairs of control lines, DTR with DSR and RTS with CTS, are both used by synchronous read() and write(). When RTS is off, the receiving function of the other unit halts automatically.[^o14-6][^o14-7] | ||
| + | |||
| + | The communication settings are the following:[^o14-7] | ||
| + | |||
| + | Table: Communication specifications | ||
| + | |||
| + | | Item | Range of values | Default setting | | ||
| + | | --- | --- | --- | | ||
| + | | Character length | 8 bits | 8 bits | | ||
| + | | Stop bit | 1 to 2 bits | 2 bits | | ||
| + | | Parity check | None | Disabled | | ||
| + | | Communication rate | 1 to 2073600 bps, divisors of 2073600 only | 9600 bps | | ||
| + | |||
| + | AddCOMB() sets DTR and RTS to 0. A synchronous or asynchronous read sets RTS to 1 when it starts and to 0 when it completes.[^o14-7] | ||
| + | |||
| + | ## Detecting the Other Unit | ||
| + | |||
| + | When the link cable is absent or the other PlayStation has no power, DSR and CTS are both 1. When the cable links two powered units, both are 0, and they stay 0 after AddCOMB(). A program can therefore set DTR or RTS to 1 briefly after AddCOMB() to tell the other unit that it is ready, and the other unit does the same, so both sides confirm each other. RTS is returned to 0 afterward so that it does not affect later reads and writes.[^o14-8] | ||
| + | |||
| + | There is no certain way to detect that the cable has been disconnected or the other unit switched off during communication. The program therefore uses a time limit. A wait callback that watches the responses of the other unit shows that something is wrong, but not whether the cause is the connection or a communication error.[^o14-8] | ||
| + | |||
| + | ## Efficiency | ||
| + | |||
| + | The read function can run in a critical section, so an EvSpIOER event handler can register the next asynchronous read and receive into a ring buffer in the background. Asynchronous write puts the heaviest load on the CPU of all modes. If receiving is not given priority, overrun errors occur, and in practice asynchronous writes above 57600 bps cannot be expected to work.[^o14-8] | ||
| + | |||
| + | The lightest load comes from synchronous writes of 8-character packets placed through the code. The timeout of the wait callback limits each write, and its return value gives the characters already sent for the next write. An asynchronous read with a unit number other than one character cannot detect data shorter than the unit, which can deadlock, so the application adds its own timeout.[^o14-9] | ||
| + | |||
| + | ## Functions | ||
| + | |||
| + | In the tables below, Introduced is the run-time library version that added the item.[^reff133] | ||
| + | |||
| + | libcomb has the following functions:[^reff133] | ||
| + | |||
| + | Table: libcomb functions | ||
| + | |||
| + | | Function | Introduced | Purpose | | ||
| + | | --- | --- | --- | | ||
| + | | `_comb_control` | 3.0 | Link cable driver control. | | ||
| + | | `AddCOMB` | 3.0 | Initialize link cable driver. | | ||
| + | | `ChangeClearSIO` | 3.0 | Clear interrupt from expanded SIO in the driver. | | ||
| + | | `DelCOMB` | 3.0 | Remove link cable driver from kernel. | | ||
| + | |||
| + | ## Macros | ||
| + | |||
| + | libcomb has the following macros:[^refm139] | ||
| + | |||
| + | Table: libcomb macros | ||
| + | |||
| + | | Macro | Introduced | Purpose | | ||
| + | | --- | --- | --- | | ||
| + | | `CombAsyncRequest` | 4.2 | Get asynchronous communication request status. | | ||
| + | | `CombBytesRemaining` | 4.2 | Get remaining transmit or receive data. | | ||
| + | | `CombBytesToRead` | 4.2 | Get number of bytes left to receive. | | ||
| + | | `CombBytesToWrite` | 4.2 | Get number of bytes left to send. | | ||
| + | | `CombCancelRead` | 4.2 | Cancel asynchronous read. | | ||
| + | | `CombCancelWrite` | 4.2 | Cancel asynchronous write. | | ||
| + | | `CombControlStatus` | 4.2 | Get control line status. | | ||
| + | | `CombCTS` | 4.2 | Get status of CTS signal. | | ||
| + | | `CombGetBPS` | 4.2 | Get communication speed. | | ||
| + | | `CombGetMode` | 4.2 | Get communication mode. | | ||
| + | | `CombGetPacketSize` | 4.2 | Get receive packet size. | | ||
| + | | `CombReset` | 4.2 | Initialize the serial controller. | | ||
| + | | `CombResetError` | 4.2 | Initialize error flags. | | ||
| + | | `CombResetVBLANK` | 4.2 | Reset vertical blanking signal. | | ||
| + | | `CombSetBPS` | 4.2 | Set communication speed. | | ||
| + | | `CombSetControl` | 4.2 | Set control line status. | | ||
| + | | `CombSetMode` | 4.2 | Set communication mode. | | ||
| + | | `CombSetPacketSize` | 4.2 | Set receive packet size. | | ||
| + | | `CombSetRTS` | 4.2 | Set RTS signal. | | ||
| + | | `CombSioStatus` | 4.2 | Get serial controller status. | | ||
| + | | `CombWaitCallback` | 4.2 | Set wait callback function. | | ||
| + | |||
| + | ## References | ||
| + | |||
| + | [^o14-3]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 14-3. | ||
| + | [^o14-4]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 14-4. | ||
| + | [^o14-5]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 14-5. | ||
| + | [^o14-6]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 14-6. | ||
| + | [^o14-7]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 14-7. | ||
| + | [^o14-8]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 14-8. | ||
| + | [^o14-9]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 14-9. | ||
| + | [^reff133]: Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 13-3 to 13-8. | ||
| + | [^refm139]: Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 13-9 to 13-29. | ||