View source for Memory Card Library (libcard)

You do not have permission to edit this page. Log in to edit.
---
title: Memory Card Library (libcard)
type: component
summary: Provides functions for reading and writing the Memory Card.
category: Psy-Q
info: Library = libcard.lib
info: Header File = libapi.h, sys/file.h
info: SDK = Psy-Q
---

## Overview

The Memory Card Library (libcard) gives smooth access to the Memory Card in a real-time environment. It reads and writes data and calls the Memory Card BIOS service.[^o5-3]

A program that uses libcard links with libcard.lib. libcard has no header file of its own, so the program includes libapi.h and sys/file.h.[^o5-3]

This library is part of the run-time library that Sony distributed with the [Psy-Q](/sdk/psy-q/) development tools.[^ptcd]

## Memory Card

The Memory Card is a memory device that keeps its data after a reset or power off, and it may be inserted or removed while the power is on. Its hardware has the following specifications:[^o5-3]

Table: Memory Card specifications

| Item | Specification |
| --- | --- |
| Capacity | 120 KB after format, accessed in 128-byte sectors |
| Communication | Synchronous serial communication sharing the controller port |
| Access speed | No access for 20 ms after reading 1 sector. Continuous reading at about 10 KB/sec at most. |
| Other | May be inserted and removed without turning the power off. 100,000 reads guaranteed. |

## Events

libcard uses two source descriptors, HwCARD and SwCARD, and no internal event descriptors. The events are the following:[^o5-3]

Table: Memory Card events

| Source descriptor | Event class | Meaning |
| --- | --- | --- |
| HwCARD | EvSpIOE | Processing complete |
| HwCARD | EvSpERROR | Card no good |
| HwCARD | EvSpTIMOUT | No card |
| SwCARD | EvSpIOE | Processing complete |
| SwCARD | EvSpERROR | Card no good |
| SwCARD | EvSpTIMOUT | No card |
| SwCARD | EvSpNEW | New card or uninitialized card |

The meaning of SwCARD EvSpNEW depends on the function that issued the request. Every vertical sync interrupt clears the HwCARD events automatically. A function that waits for the vertical interrupt, such as VSync(), therefore runs the risk that the program misses an HwCARD event.[^o5-3][^o5-4]

## BIOS

The BIOS checks the card connection, tests the logical format and accesses the card in 128-byte sectors. To share the port with the controller and serve both connectors, it accesses the card once every two vertical blanks and reads one sector in each access. After the vertical blank interrupt the controller is read, the card connection is checked and then the hardware is checked, and the data is sent and received byte by byte on receive interrupts.[^o5-4]

The effective speed is therefore 30 sectors per second, or 3.75 KB/sec. The CPU load is 2.5% when reading continuously from 2 cards and 3.2% when writing continuously to 2 cards.[^o5-4]

## Card Test

A card is tested in five steps. _card_info() tests for a card. An IOE event means that a confirmed card is still in its slot, and the program goes on to the file system. A NEWCARD event means that an unconfirmed card is in the slot. A TIMOUT event means that the slot is empty, although a communication error is possible, and the test is retried.[^o5-4]

For a new card, _card_clear() confirms it, and _card_load() tests its logical format. An IOE event means that the card is formatted, and a NEWCARD event means that it is not and must be formatted with format(). In any other case the card was removed or a communication error occurred, and the program returns to the first step. After these steps the program reads and writes the card through the file system.[^o5-4]

## Unconfirm Flag

The card has a bit called the unconfirm flag, which is set when the card is inserted and cleared by _card_clear(). The flag therefore detects a card replacement. By default a card with the flag set cannot be read or written, and any attempt is an error. _new_card() masks this test so that the card can be accessed for testing.[^o5-4][^o5-5]

## File System

The Memory Card file system has the following parameters:[^o5-6]

Table: Memory Card file system

| Item | Value |
| --- | --- |
| Device name | buX0, where X is the connector number 0 or 1 |
| File name | ASCII characters, up to 21 |
| Directory structure | None |
| Control unit | Slot of 8 KB (64 sectors), the unit of file size |
| Number of slots | 15 per card, so at most 15 files |
| Automatic replacement sectors | 20 per card |

The kernel services that take a file name work on all bu devices. The size of a file is given in slots when the file is created and cannot change afterward, and the file system joins the fragments left by deleted files to provide the space.[^o5-7]

The bu device is designed for a real-time environment and supports non-blocking mode. With O_NOWAIT in open(), read() and write() return as soon as the request is registered in the driver, and an event reports the end of the transfer. A slot accepts only one request at a time.[^o5-7]

## Rules for Use

The Memory Card is a resource shared by many applications, so it is used according to common rules. No standard screen is defined for a full or unformatted card, and each application designs its own. The application always asks the user before it formats a card and never formats automatically. When no card is found and this limits later play, it tells the user and asks whether to continue. The product catalog gives the required space in blocks, and a block is a slot of 8 KB.[^o5-7][^o5-8]

A file name has the following parts:[^o5-8]

Table: Memory Card file names

| Bytes | Contents | Notes |
| --- | --- | --- |
| 0 | Magic number | Always 'B' |
| 1 | Region | Japan 'I', North America 'A', Europe 'E' |
| 2 to 11 | Title | SCE product number, of the first disc for multi-disc titles |
| 12 to 20 | User | ASCII other than 0x00, 0x2a (*) and 0x3f (?), ending with 0x00 |

The SCE product number is set by the Release Planning Committee about three weeks before the master is released. For the product code SLPS-00001 the first 12 characters are BISLPS-00001, with the number always padded to five digits.[^o5-8]

Each file starts with the following header:[^o5-8][^o5-9]

Table: Memory Card file header

| Item | Size (bytes) |
| --- | --- |
| Magic number | 2 (always "SC") |
| Type | 1 |
| Number of slots | 1 |
| Text name | 64 (Shift JIS, full-size 32 characters) |
| Pad | 28 (all 0x00) |
| CLUT | 32 |
| Icon image (1) | 128 (16 x 16 x 4 bits) |
| Icon image (2) | 128 (type 0x12 and 0x13 only) |
| Icon image (3) | 128 (type 0x13 only) |
| Data | 128 x N |

The type field gives the number of icon images in the automatically replaced animation. Type 0x11 has one image and 0x12 has two. Type 0x13 has three.[^o5-9]

## Protecting Written Data

A reset, a card removal or a power off during a write can destroy the data, and the replacement sector function covers only write errors in the card memory. The hardware and the library do not protect the contents of a write. An application therefore writes its data twice in alternation and puts a checksum in the last byte of each sector. When it reads, it tests the checksum and uses the other copy if an error is found.[^o5-9]

Static discharge or power supply noise can make an access fail even when the card and the program are correct. The test for a card, the writes and the reads are therefore retried at intervals of 1 to 2 seconds.[^o5-10]

## Known Bugs

A read() or write() issued right after open() fails, so a file created with open() is closed with close() first. In asynchronous access with read() the file pointer advances 128 bytes too little and is corrected with lseek(). Before library 3.7, controller A read all buttons as released in a frame in which a timeout occurred on card A. The manual also advises calling _new_card() before _card_info() to suppress EvSpNEW events.[^o5-10][^o5-11]

## Functions

In the tables below, Introduced is the run-time library version that added the item.[^reff43]

libcard has the following functions:[^reff43]

Table: libcard functions

| Function | Introduced | Purpose |
| --- | --- | --- |
| `InitCARD` | 3.0 | Initialize Memory Card BIOS. |
| `StartCARD` | 3.0 | Start Memory Card BIOS. |
| `StopCARD` | 3.0 | Stop Memory Card BIOS. |
| `_bu_init` | 3.0 | Initialize Memory Card file system. |
| `_card_auto` | 3.0 | Set automatic format function. |
| `_card_chan` | 3.0 | Get a Memory Card BIOS event. |
| `_card_clear` | 3.0 | Clear unconfirmed flags. |
| `_card_format` | 3.0 | Format the Memory Card. |
| `_card_info` | 3.0 | Get card status. |
| `_card_load` | 3.0 | Test logical format. |
| `_card_read` | 3.0 | Read one block from the Memory Card. |
| `_card_status` | 3.0 | Get Memory Card BIOS status. |
| `_card_wait` | 3.0 | Wait for Memory Card BIOS completion. |
| `_card_write` | 3.0 | Write to one block of the Memory Card (for testing only). |
| `_new_card` | 3.0 | Change settings of unconfirmed flag test. |

## References

[^o5-3]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 5-3.
[^o5-4]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 5-4.
[^o5-5]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 5-5.
[^o5-6]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 5-6.
[^o5-7]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 5-7.
[^o5-8]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 5-8.
[^o5-9]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 5-9.
[^o5-10]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 5-10.
[^o5-11]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 5-11.
[^reff43]: Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 4-3 to 4-17.
[^ptcd]: Sony Computer Entertainment Inc. Programmer Tools CD (DTL-S2002), README.TXT. 11/26/96. Section "CD-ROM Contents - Highlights", directories \PSX and \PSYQ.