KITAQFC

Indique si la cible de compilation est FDS, par exemple pour afficher des informations propres à la cible dans du code de jeu partagé.

Syntaxe

u8 __fds_available(void);

Valeur renvoyée

1 pour une compilation FDS, sinon 0. Il ne s’agit pas d’une détection de périphérique à l’exécution.

Conditions et limites

Cette requête est valide pour les cibles cartouche comme NROM. Placer une API réservée au FDS dans if (__fds_available()) ne la dispense pas des vérifications de cible ; organisez le code source selon la cible.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    fds_result[0] = __fds_available();
    m_init();
    m_text(2,2,"FDS BUILD SELECTION"); m_wait();
    m_text(2,5,"FDS=1 / CARTRIDGE=0"); m_wait();
    m_number(fds_result[0]); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

La version FDS affiche 001 et la version NROM affiche 000. Le même code C renvoie une valeur différente selon la cible de compilation, indépendamment de la présence d’un disque.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_available.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_available.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
# Cartridge comparison
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_available.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_available.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Return the compile-time FDS mapper selection as 0 or 1; this is not a hardware probe.

if (funcName == "__fds_available")
            {
                if (!Need(0)) return true;
                EmitAsm("LDA", Imm(isFds ? 1 : 0));
                return true;
            }

Vérifie immédiatement la présence du disque, permettant à un écran d’insertion de l’interroger une fois par image sans bloquer.

Syntaxe

u8 __fds_disk_ready(void);

Valeur renvoyée

Renvoie 1 lorsque le bit 0 de $4032 est à zéro, et 0 lorsqu’il est à un.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

Le test utilise le bit 0 de $4032, qui indique la présence du disque. Il ne vérifie ni la disponibilité du lecteur signalée par le bit 1, ni l’existence d’un fichier, ni la fin d’un chargement. Le mot « ready » ne signifie pas ici qu’un transfert peut commencer.

KUROSAKI utilise un modèle partiel du contrôleur FDS. Cet exemple observe une présence de 1, un masque de protection de 0 et un statut de 0 ; la capture ne permet pas d’établir le comportement en cas d’éjection, de support protégé ou d’erreur CRC.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

NESdev : registres matériels FDS

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    fds_result[0] = __fds_disk_ready();
    fds_result[1] = __fds_side();
    fds_result[2] = __fds_error();
    fds_result[3] = 0;
    // Never enter an unbounded wait without first checking disk presence.
    if (fds_result[0]) {
        __fds_wait_ready(); fds_result[3]++;
        __fds_wait_insert(); fds_result[3]++;
    }
    m_init();
    m_text(2,2,"FDS REGISTER STATUS"); m_wait();
    m_text(2,5,"PRESENT / PROTECT / STATUS"); m_wait();
    m_put(2,7,'0'+fds_result[0]);
    m_put(12,7,'0'+fds_result[1]);
    m_put(22,7,'0'+fds_result[2]); m_wait();
    m_text(2,10,"COMPLETED PRESENCE WAITS"); m_wait();
    m_put(2,12,'0'+fds_result[3]); m_wait();
    m_text(2,15,"NO FILE TRANSFER TESTED"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Sous PRESENT / PROTECT / STATUS, l’écran affiche 1 / 0 / 0, puis 2 sous COMPLETED PRESENCE WAITS. Les deux attentes de présence sont revenues ; ce n’est pas un indicateur de réussite d’un transfert de fichier. NO FILE TRANSFER TESTED apparaît en dessous.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_status.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_status.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Return the inverted disk-absent bit from 4032 as 0 or 1; this checks presence, not transfer completion.

case "__fds_disk_ready":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Mem(0x4032));
                    EmitAsm("AND", Imm(0x01));
                    EmitAsm("EOR", Imm(0x01));
                    return true;
                // Expose status bit 2 as the raw mask value 0 or 4, rather than a normalized Boolean.

Lit le registre d’état matériel FDS à $4030. Ce n’est pas une erreur mémorisée de la dernière opération disque.

Syntaxe

u8 __fds_error(void);

Valeur renvoyée

Renvoie la valeur complète sur huit bits de $4030. Conservez le résultat de __fds_load_file() ou __fds_save_file() pour traiter les codes d’erreur BIOS.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

KUROSAKI utilise un modèle partiel du contrôleur FDS. Cet exemple observe une présence de 1, un masque de protection de 0 et un statut de 0 ; la capture ne permet pas d’établir le comportement en cas d’éjection, de support protégé ou d’erreur CRC.

Lire le statut acquitte aussi les demandes d’interruption. Évitez les interrogations indiscriminées si un autre gestionnaire dépend du même statut. KUROSAKI efface son indicateur d’IRQ FDS en attente lors de cette lecture.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

NESdev : registres matériels FDS

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    fds_result[0] = __fds_disk_ready();
    fds_result[1] = __fds_side();
    fds_result[2] = __fds_error();
    fds_result[3] = 0;
    // Never enter an unbounded wait without first checking disk presence.
    if (fds_result[0]) {
        __fds_wait_ready(); fds_result[3]++;
        __fds_wait_insert(); fds_result[3]++;
    }
    m_init();
    m_text(2,2,"FDS REGISTER STATUS"); m_wait();
    m_text(2,5,"PRESENT / PROTECT / STATUS"); m_wait();
    m_put(2,7,'0'+fds_result[0]);
    m_put(12,7,'0'+fds_result[1]);
    m_put(22,7,'0'+fds_result[2]); m_wait();
    m_text(2,10,"COMPLETED PRESENCE WAITS"); m_wait();
    m_put(2,12,'0'+fds_result[3]); m_wait();
    m_text(2,15,"NO FILE TRANSFER TESTED"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Sous PRESENT / PROTECT / STATUS, l’écran affiche 1 / 0 / 0, puis 2 sous COMPLETED PRESENCE WAITS. Les deux attentes de présence sont revenues ; ce n’est pas un indicateur de réussite d’un transfert de fichier. NO FILE TRANSFER TESTED apparaît en dessous.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_status.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_status.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read the entire 4030 status register; this is not a stored BIOS error code.

case "__fds_error":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Mem(0x4030));
                    return true;

Renvoie le bit de protection en écriture masqué de $4032. Cette fonction n’identifie pas la face A ou B du disque.

Syntaxe

u8 __fds_side(void);

Valeur renvoyée

Renvoie $4032 & 0x04, soit 0 ou 4, et non un booléen normalisé. Le bit matériel 2 indique une protection en écriture ou un disque éjecté.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

KUROSAKI utilise un modèle partiel du contrôleur FDS. Cet exemple observe une présence de 1, un masque de protection de 0 et un statut de 0 ; la capture ne permet pas d’établir le comportement en cas d’éjection, de support protégé ou d’erreur CRC.

Pour tester la protection, utilisez (__fds_side() != 0). La présence du disque et le résultat de l’opération BIOS sont aussi nécessaires pour déterminer si la sauvegarde réussit.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

NESdev : registres matériels FDS

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    fds_result[0] = __fds_disk_ready();
    fds_result[1] = __fds_side();
    fds_result[2] = __fds_error();
    fds_result[3] = 0;
    // Never enter an unbounded wait without first checking disk presence.
    if (fds_result[0]) {
        __fds_wait_ready(); fds_result[3]++;
        __fds_wait_insert(); fds_result[3]++;
    }
    m_init();
    m_text(2,2,"FDS REGISTER STATUS"); m_wait();
    m_text(2,5,"PRESENT / PROTECT / STATUS"); m_wait();
    m_put(2,7,'0'+fds_result[0]);
    m_put(12,7,'0'+fds_result[1]);
    m_put(22,7,'0'+fds_result[2]); m_wait();
    m_text(2,10,"COMPLETED PRESENCE WAITS"); m_wait();
    m_put(2,12,'0'+fds_result[3]); m_wait();
    m_text(2,15,"NO FILE TRANSFER TESTED"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Sous PRESENT / PROTECT / STATUS, l’écran affiche 1 / 0 / 0, puis 2 sous COMPLETED PRESENCE WAITS. Les deux attentes de présence sont revenues ; ce n’est pas un indicateur de réussite d’un transfert de fichier. NO FILE TRANSFER TESTED apparaît en dessous.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_status.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_status.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Return raw status mask 4032 & 04, either 0 or 4. This is not a numbered disk-side identifier.

case "__fds_side":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Mem(0x4032));
                    EmitAsm("AND", Imm(0x04));
                    return true;
                // Read status register 4030 directly; the caller receives its complete byte value.

Exprime une attente d’insertion de disque. Appelle la même boucle de détection de présence que __fds_wait_ready().

Syntaxe

void __fds_wait_insert(void);

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

Le test utilise le bit 0 de $4032, qui indique la présence du disque. Il ne vérifie ni la disponibilité du lecteur signalée par le bit 1, ni l’existence d’un fichier, ni la fin d’un chargement. Le mot « ready » ne signifie pas ici qu’un transfert peut commencer.

Il n’y a pas de délai d’expiration. Sans disque, l’appel reste bloqué. Interrogez __fds_disk_ready() une fois par image si le jeu doit continuer à mettre l’affichage à jour ou à accepter des entrées. L’exemple vérifie la présence avant chacune des deux attentes. Un disque déjà inséré suffit à terminer l’attente, sans nouveau cycle de retrait et d’insertion.

KUROSAKI utilise un modèle partiel du contrôleur FDS. Cet exemple observe une présence de 1, un masque de protection de 0 et un statut de 0 ; la capture ne permet pas d’établir le comportement en cas d’éjection, de support protégé ou d’erreur CRC.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

NESdev : registres matériels FDS

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    fds_result[0] = __fds_disk_ready();
    fds_result[1] = __fds_side();
    fds_result[2] = __fds_error();
    fds_result[3] = 0;
    // Never enter an unbounded wait without first checking disk presence.
    if (fds_result[0]) {
        __fds_wait_ready(); fds_result[3]++;
        __fds_wait_insert(); fds_result[3]++;
    }
    m_init();
    m_text(2,2,"FDS REGISTER STATUS"); m_wait();
    m_text(2,5,"PRESENT / PROTECT / STATUS"); m_wait();
    m_put(2,7,'0'+fds_result[0]);
    m_put(12,7,'0'+fds_result[1]);
    m_put(22,7,'0'+fds_result[2]); m_wait();
    m_text(2,10,"COMPLETED PRESENCE WAITS"); m_wait();
    m_put(2,12,'0'+fds_result[3]); m_wait();
    m_text(2,15,"NO FILE TRANSFER TESTED"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Sous PRESENT / PROTECT / STATUS, l’écran affiche 1 / 0 / 0, puis 2 sous COMPLETED PRESENCE WAITS. Les deux attentes de présence sont revenues ; ce n’est pas un indicateur de réussite d’un transfert de fichier. NO FILE TRANSFER TESTED apparaît en dessous.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_status.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_status.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Alias the same disk-presence wait as __fds_wait_ready; the call can block indefinitely.

EmitHelperStart("__fds_wait_ready");
            string loop = NewGeneratedLabel("fds_wait_ready_loop");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LDA", Mem(0x4032));
            EmitAsm("AND", Imm(0x01));
            EmitAsm("BNE", Rel(loop));
            EmitAsm("RTS");

Attend dans une boucle d’interrogation CPU jusqu’à la présence d’un disque.

Syntaxe

void __fds_wait_ready(void);

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

Le test utilise le bit 0 de $4032, qui indique la présence du disque. Il ne vérifie ni la disponibilité du lecteur signalée par le bit 1, ni l’existence d’un fichier, ni la fin d’un chargement. Le mot « ready » ne signifie pas ici qu’un transfert peut commencer.

Il n’y a pas de délai d’expiration. Sans disque, l’appel reste bloqué. Interrogez __fds_disk_ready() une fois par image si le jeu doit continuer à mettre l’affichage à jour ou à accepter des entrées. L’exemple vérifie la présence avant chacune des deux attentes. Un disque déjà inséré suffit à terminer l’attente, sans nouveau cycle de retrait et d’insertion.

KUROSAKI utilise un modèle partiel du contrôleur FDS. Cet exemple observe une présence de 1, un masque de protection de 0 et un statut de 0 ; la capture ne permet pas d’établir le comportement en cas d’éjection, de support protégé ou d’erreur CRC.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

NESdev : registres matériels FDS

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    fds_result[0] = __fds_disk_ready();
    fds_result[1] = __fds_side();
    fds_result[2] = __fds_error();
    fds_result[3] = 0;
    // Never enter an unbounded wait without first checking disk presence.
    if (fds_result[0]) {
        __fds_wait_ready(); fds_result[3]++;
        __fds_wait_insert(); fds_result[3]++;
    }
    m_init();
    m_text(2,2,"FDS REGISTER STATUS"); m_wait();
    m_text(2,5,"PRESENT / PROTECT / STATUS"); m_wait();
    m_put(2,7,'0'+fds_result[0]);
    m_put(12,7,'0'+fds_result[1]);
    m_put(22,7,'0'+fds_result[2]); m_wait();
    m_text(2,10,"COMPLETED PRESENCE WAITS"); m_wait();
    m_put(2,12,'0'+fds_result[3]); m_wait();
    m_text(2,15,"NO FILE TRANSFER TESTED"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Sous PRESENT / PROTECT / STATUS, l’écran affiche 1 / 0 / 0, puis 2 sous COMPLETED PRESENCE WAITS. Les deux attentes de présence sont revenues ; ce n’est pas un indicateur de réussite d’un transfert de fichier. NO FILE TRANSFER TESTED apparaît en dessous.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_status.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_status.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Poll disk presence until the absent bit clears. There is no timeout or cancellation path.

EmitHelperStart("__fds_wait_ready");
            string loop = NewGeneratedLabel("fds_wait_ready_loop");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LDA", Mem(0x4032));
            EmitAsm("AND", Imm(0x01));
            EmitAsm("BNE", Rel(loop));
            EmitAsm("RTS");

Vérifie si les métadonnées de fichiers compilées contiennent l’ID demandé. Un enregistrement de taille nulle compte tout de même comme présent.

Syntaxe

u8 __fds_file_exists(u8 id);

Paramètres

id

Identifiant de fichier à rechercher. Les métadonnées utilisent les ID 0 à 254 ; 255 est réservé au terminateur. Un ID est distinct d’un numéro de fichier, d’un nom de fichier ou d’une adresse de destination.

Valeur renvoyée

1 si la table compilée contient l’ID, sinon 0. Cela ne garantit pas que le disque inséré contient ce fichier.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

Recherche dans la table compilée depuis --fds-meta=... ou --fds-manifest=..., ainsi que dans les enregistrements d’overlays générés. Cette fonction ne lit pas le répertoire du disque. Un fichier sans entrée dans la table n’est pas trouvé, même s’il figure dans l’image disque. Les enregistrements manuels et générés sont limités à 42 au total.

La taille est la valeur déclarée dans les métadonnées. Elle n’est pas nécessairement égale à la longueur déduite du fichier source, à la taille utile d’un overlay raccourci ou au contenu d’un disque remplacé. Déclarez des tailles exactes si vous utilisez ces requêtes pour borner les accès aux données.

Placez fds_metadata.json et ses deux fichiers .bin à côté du code C. L’ID 16 contient une séquence originale de 513 octets : deux fois 0..255, puis zéro. L’ID 17 a un contenu vide. Tous deux sont des fichiers PRG non destinés au démarrage (type 0), et cette leçon ne les charge pas. Les chemins source relatifs sont résolus depuis le dossier du manifeste.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    fds_result[0] = __fds_file_exists(16);
    fds_sizes[0] = __fds_file_size(16);
    fds_result[1] = __fds_file_exists(17);
    fds_sizes[1] = __fds_file_size(17);
    fds_result[2] = __fds_file_exists(18);
    fds_sizes[2] = __fds_file_size(18);
    m_init();
    m_text(2,2,"FDS COMPILED FILE TABLE"); m_wait();
    m_text(2,5,"ID    EXISTS    BYTES"); m_wait();
    m_text(2,7,"16      1        513"); m_wait();
    m_text(2,9,"17      1          0"); m_wait();
    m_text(2,11,"18      0          0"); m_wait();
    if (fds_result[0]==1 && fds_sizes[0]==513 &&
        fds_result[1]==1 && fds_sizes[1]==0 &&
        fds_result[2]==0 && fds_sizes[2]==0) { m_text(2,14,"TABLE VALUES MATCH: PASS"); }
    else { m_text(2,14,"TABLE VALUES MATCH: FAIL"); }
    m_wait();
    m_text(2,17,"NO DISK DIRECTORY SCAN"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le tableau indique que l’ID 16 existe avec 513 octets, que l’ID 17 existe avec zéro octet et que l’ID 18 est absent avec zéro octet. TABLE VALUES MATCH: PASS compare les valeurs obtenues à cette combinaison. Une taille nulle ne suffit pas à distinguer un enregistrement vide d’un ID absent.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_metadata.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_metadata.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm --fds-meta=.\kitaq-docs\samples\api-examples\fc\fds_metadata.json

Query the compiled --fds-meta/--fds-manifest table, not the inserted disk; return 0 or 1.

EmitHelperStart("__fds_file_exists");
            EmitFdsMetadataSearch(foundReturnsSize: false);

            // Return the compiled metadata size, using zero for an unmatched ID.

Renvoie la taille en octets déclarée pour un ID dans les métadonnées compilées, par exemple pour consulter la taille de chargement prévue d’une ressource.

Syntaxe

u16 __fds_file_size(u8 id);

Paramètres

id

Identifiant de fichier à rechercher. Les métadonnées utilisent les ID 0 à 254 ; 255 est réservé au terminateur. Un ID est distinct d’un numéro de fichier, d’un nom de fichier ou d’une adresse de destination.

Valeur renvoyée

Taille déclarée non signée sur 16 bits, de 0 à 65535. Les ID absents renvoient aussi zéro ; utilisez __fds_file_exists() si cette distinction est nécessaire.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

Recherche dans la table compilée depuis --fds-meta=... ou --fds-manifest=..., ainsi que dans les enregistrements d’overlays générés. Cette fonction ne lit pas le répertoire du disque. Un fichier sans entrée dans la table n’est pas trouvé, même s’il figure dans l’image disque. Les enregistrements manuels et générés sont limités à 42 au total.

La taille est la valeur déclarée dans les métadonnées. Elle n’est pas nécessairement égale à la longueur déduite du fichier source, à la taille utile d’un overlay raccourci ou au contenu d’un disque remplacé. Déclarez des tailles exactes si vous utilisez ces requêtes pour borner les accès aux données.

Placez fds_metadata.json et ses deux fichiers .bin à côté du code C. L’ID 16 contient une séquence originale de 513 octets : deux fois 0..255, puis zéro. L’ID 17 a un contenu vide. Tous deux sont des fichiers PRG non destinés au démarrage (type 0), et cette leçon ne les charge pas. Les chemins source relatifs sont résolus depuis le dossier du manifeste.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    fds_result[0] = __fds_file_exists(16);
    fds_sizes[0] = __fds_file_size(16);
    fds_result[1] = __fds_file_exists(17);
    fds_sizes[1] = __fds_file_size(17);
    fds_result[2] = __fds_file_exists(18);
    fds_sizes[2] = __fds_file_size(18);
    m_init();
    m_text(2,2,"FDS COMPILED FILE TABLE"); m_wait();
    m_text(2,5,"ID    EXISTS    BYTES"); m_wait();
    m_text(2,7,"16      1        513"); m_wait();
    m_text(2,9,"17      1          0"); m_wait();
    m_text(2,11,"18      0          0"); m_wait();
    if (fds_result[0]==1 && fds_sizes[0]==513 &&
        fds_result[1]==1 && fds_sizes[1]==0 &&
        fds_result[2]==0 && fds_sizes[2]==0) { m_text(2,14,"TABLE VALUES MATCH: PASS"); }
    else { m_text(2,14,"TABLE VALUES MATCH: FAIL"); }
    m_wait();
    m_text(2,17,"NO DISK DIRECTORY SCAN"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le tableau indique que l’ID 16 existe avec 513 octets, que l’ID 17 existe avec zéro octet et que l’ID 18 est absent avec zéro octet. TABLE VALUES MATCH: PASS compare les valeurs obtenues à cette combinaison. Une taille nulle ne suffit pas à distinguer un enregistrement vide d’un ID absent.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_metadata.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_metadata.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm --fds-meta=.\kitaq-docs\samples\api-examples\fc\fds_metadata.json

Return the compiled metadata size, or zero if id is absent. No disk directory is read.

EmitHelperStart("__fds_file_size");
            EmitFdsMetadataSearch(foundReturnsSize: true);

Lit un fichier via le BIOS et copie ses données PRG dans un tampon CPU. Utilisez cette fonction pour charger des sauvegardes ou des ressources de niveau dans la mémoire réservée par le jeu.

Syntaxe

u8 __fds_load_file(u8 id, u8* dst);

Paramètres

id

Identifiant d’un fichier non destiné au démarrage, inclus dans le disque généré, de 0 à 254 ; l’exemple utilise 73. Il est distinct de la position physique du fichier. L’ID 255, les identifiants absents et les fichiers de démarrage sont refusés.

dst

Destination d’un fichier PRG, avec assez de place pour toute sa longueur empaquetée. Passez zéro pour laisser les données à la destination définie dans l’en-tête, sans copie. Pour les fichiers PPU CHR ou de table de noms, seul zéro est accepté ; le BIOS transfère vers la destination PPU native.

Valeur renvoyée

Zéro en cas de succès. Les erreurs BIOS non nulles sont renvoyées telles quelles. Si le BIOS annonce un succès sans avoir chargé exactement un fichier, le résultat est 64 ($40). Un identifiant, un tampon ou une combinaison type de fichier/destination invalide renvoie 255 ($FF).

Conditions et limites

Utilisez cette API avec --mapper=fds --fds-layout=fds32. Le manifeste --fds-meta définit les identifiants de fichiers, les adresses de chargement, les types, le statut de démarrage et l’ordre. Les adresses et tailles de transfert proviennent de l’image disque produite par la compilation ; cette API n’inspecte pas un disque quelconque inséré.

Le BIOS charge d’abord à l’adresse stockée dans l’en-tête du disque, puis cette fonction copie vers dst. Elle choisit le sens de copie pour préserver les données en cas de chevauchement, mais la zone intermédiaire doit également être réservée. Un transfert échoué ne copie rien vers dst. Après un appel BIOS, la banque résidente est marquée 255 (inconnue).

Chaque tampon CPU doit tenir entièrement dans $0200–$07FF ou dans $6000–$DFFF. Les plages qui bouclent dans l’espace d’adressage et les destinations dans les registres d’E/S sont refusées. L’appelant doit aussi éviter tout chevauchement avec le code, l’OAM, les autres variables et les zones temporaires du compilateur. L’exemple utilise la banque 0 pour le code commun, $8000 pour la zone intermédiaire et deux tampons de quatre octets à $8500 et $8600.

Ces appels BIOS sont synchrones. Appelez-les depuis le code commun pour que le transfert n’écrase ni le code en cours d’exécution ni son adresse de retour ; ne les appelez pas depuis un gestionnaire d’interruption. Respectez les prérequis du BIOS pendant les E/S disque : arrêtez le rendu et la NMI, réglez l’incrément d’adresse PPU à un et désactivez les sources d’IRQ autres que le disque. La continuité du jeu ou de la musique pendant le transfert n’est pas garantie.

La capture utilise un programme de test original de la convention d’appel BIOS pour vérifier le code CPU compilé, le contenu des tampons, la sauvegarde suivie d’une relecture et chaque pixel affiché. Elle ne vérifie ni le véritable BIOS, ni les écritures sur disque physique, ni le CRC, ni la récupération après coupure de courant. Une exécution FDS ordinaire dans KUROSAKI ne suffit pas à établir le même comportement de sauvegarde.

Utilisez l’exemple avec fds_file_io_manifest.json et fds_file_io_payload.bin du même dossier. Le vérificateur ci-dessous génère un programme de test temporaire à partir de sources originales, puis le supprime. Aucun BIOS commercial n’est inclus, et ce programme de test n’est pas un BIOS destiné aux jeux ordinaires.

Convention d’appel du BIOS FDS

Exemple d’utilisation

#pragma fixed_bank 0
#include "fc_fds_scene.h"
void main(void) {
    u8 i;
    u8* data=(u8*)0x8500;
    u8* again=(u8*)0x8600;
    __irq_disable();__ppu_ctrl_set(0);__ppu_mask_set(0);
    // Keep rendering/NMI and non-disk IRQ sources disabled during disk I/O.
    *((u8*)0xFF)=0;*((u8*)0x4010)=0;*((u8*)0x4017)=0x40;*((u8*)0x4022)=0;
    fds_result[0]=__fds_load_file(73,data);
    fds_result[1]=data[0];fds_result[2]=data[3];
    for(i=0;i<4;i=i+1){data[i]=(i+1)*7;}
    fds_result[3]=__fds_save_file(73,data,4);
    fds_result[4]=__fds_load_file(73,again);
    fds_result[5]=again[0];fds_result[6]=again[3];
    // Check every returned byte, not only the displayed endpoints.
    for(i=0;i<4;i=i+1){if(again[i]!=(i+1)*7){fds_result[7]=1;}}
    fds_result[15]=165;
    m_init();m_text(2,2,"FDS LOAD / SAVE BUFFER");m_wait();
    m_text(2,5,"LOAD TO 8500 STATUS");fds_number(25,5,fds_result[0]);m_wait();
    m_text(2,7,"INITIAL FIRST/LAST");fds_number(21,7,fds_result[1]);fds_number(25,7,fds_result[2]);m_wait();
    m_text(2,9,"SAVE FILE 73 STATUS");fds_number(25,9,fds_result[3]);m_wait();
    m_text(2,11,"RELOAD TO 8600 STATUS");fds_number(25,11,fds_result[4]);m_wait();
    m_text(2,13,"SAVED FIRST / LAST");fds_number(21,13,fds_result[5]);fds_number(25,13,fds_result[6]);m_wait();
    m_text(2,15,"BYTE CHECK ERRORS");fds_number(25,15,fds_result[7]);m_wait();
    m_text(2,18,"STAGING 8000 / SIZE 4");m_wait();
    while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

LOAD, SAVE, RELOAD STATUS et BYTE CHECK ERRORS affichent tous 000. INITIAL FIRST/LAST affiche 011 et 044, premier et dernier des quatre octets chargés à $8500. L’exemple les remplace par 7, 14, 21 et 28, les sauvegarde puis les recharge à $8600 : SAVED FIRST / LAST affiche donc 007 et 028. STAGING 8000 / SIZE 4 indique l’adresse de chargement définie sur disque et la longueur du fichier. Le test indépendant vérifie également que l’ID 73 est sauvegardé dans le quatrième fichier physique, à la position 3 en comptant depuis zéro.

Programme d’exemple complet

fds_file_io_manifest.json

fds_file_io_payload.bin

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_file_io.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_file_io.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --fds-meta=.\kitaq-docs\samples\api-examples\fc\fds_file_io_manifest.json --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
python .\kitaq-docs\tools\check_fds_file_examples.py

Native FDS32: load a non-boot file at its disk-header address, then memmove
PRG bytes to dst. Null dst keeps the native destination (also for PPU files).
Both CPU spans must fit $0200-$07FF or $6000-$DFFF and be owned by the caller.
Return 0, a BIOS error, $40 for a missing transfer, or $FF for invalid input.
Call from common code with disk-I/O interrupt/display prerequisites satisfied.

EmitHelperStart("__fds_load_file");
            // Load at the on-disk staging address, then memmove PRG data to non-null dst.
            EmitAsm("JSR", Abs("__kq_fds_find_io"));
            EmitAsm("CMP", Imm(0));
            EmitAsm("BNE", Rel("__kq_fio_load_invalid"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 19));
            EmitAsm("BMI", Rel("__kq_fio_load_invalid"));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 14));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 15));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 23));
            EmitAsm("STA", Mem(CallArgBase + 10));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 24));
            EmitAsm("STA", Mem(CallArgBase + 11));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 20));
            EmitAsm("BNE", Rel("__kq_fio_load_ppu"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 21));
            EmitAsm("STA", Mem(CallArgBase + 8));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 22));
            EmitAsm("STA", Mem(CallArgBase + 9));
            EmitAsm("JSR", Abs("__kq_fds_check_span"));
            EmitAsm("CMP", Imm(0));
            EmitAsm("BNE", Rel("__kq_fio_load_invalid"));
            EmitAsm("JMP", Abs("__kq_fio_load_dst"));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_load_ppu"));
            // CHR/nametable files have no CPU buffer; null dst selects their native PPU destination.
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 14));
            EmitAsm("ORA", Mem(_runtimeFdsFileHeaderAddress + 15));
            EmitAsm("BNE", Rel("__kq_fio_load_invalid"));
            EmitAsm("JMP", Abs("__kq_fio_load_bios"));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_load_dst"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 14));
            EmitAsm("ORA", Mem(_runtimeFdsFileHeaderAddress + 15));
            EmitAsm("BEQ", Rel("__kq_fio_load_bios"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 14));
            EmitAsm("STA", Mem(CallArgBase + 8));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 15));
            EmitAsm("STA", Mem(CallArgBase + 9));
            EmitAsm("JSR", Abs("__kq_fds_check_span"));
            EmitAsm("CMP", Imm(0));
            EmitAsm("BNE", Rel("__kq_fio_load_invalid"));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_load_bios"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 17));
            EmitAsm("STA", Mem(_runtimeFdsLoadListAddress));
            EmitAsm("LDA", Imm(0xFF));
            EmitAsm("STA", Mem(_runtimeFdsLoadListAddress + 1));
            EmitAsm("JSR", Mem(0xE1F8));
            _assembly.Add(Expr.Make(Tag.Word, string.Format("${0:X4}", _runtimeFdsFileHeaderAddress + 33)));
            _assembly.Add(Expr.Make(Tag.Word, string.Format("${0:X4}", _runtimeFdsLoadListAddress)));
            EmitAsm("TAX");
            EmitAsm("LDA", Imm(0xFF));
            EmitAsm("STA", Mem(_runtimeFdsResidentBankAddress));
            EmitAsm("STA", Mem(_runtimeCurrentBankAddress));
            EmitAsm("TXA");
            EmitAsm("BNE", Rel("__kq_fio_load_return"));
            EmitAsm("CPY", Imm(1));
            EmitAsm("BEQ", Rel("__kq_fio_load_count_ok"));
            EmitAsm("LDA", Imm(0x40));
            EmitAsm("RTS");
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_load_count_ok"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 14));
            EmitAsm("ORA", Mem(_runtimeFdsFileHeaderAddress + 15));
            EmitAsm("BEQ", Rel("__kq_fio_load_ok"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 21));
            EmitAsm("STA", Mem(CallArgBase + 0));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 14));
            EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 23));
            EmitAsm("STA", Mem(CallArgBase + 4));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 22));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 15));
            EmitAsm("STA", Mem(CallArgBase + 3));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 24));
            EmitAsm("STA", Mem(CallArgBase + 5));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("ORA", Mem(CallArgBase + 5));
            EmitAsm("BEQ", Rel("__kq_fio_load_ok"));
            // Copy backwards when destination starts above source, including overlapping buffers.
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("CMP", Mem(CallArgBase + 1));
            EmitAsm("BCC", Rel("__kq_fio_forward"));
            EmitAsm("BNE", Rel("__kq_fio_back_setup"));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("CMP", Mem(CallArgBase + 0));
            EmitAsm("BCC", Rel("__kq_fio_forward"));
            EmitAsm("BEQ", Rel("__kq_fio_load_ok"));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_back_setup"));
            EmitAsm("CLC");
            EmitAsm("LDA", Mem(CallArgBase + 0));
            EmitAsm("ADC", Mem(CallArgBase + 4));
            EmitAsm("STA", Mem(CallArgBase + 0));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("ADC", Mem(CallArgBase + 5));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("CLC");
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("ADC", Mem(CallArgBase + 4));
            EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("ADC", Mem(CallArgBase + 5));
            EmitAsm("STA", Mem(CallArgBase + 3));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_backward"));
            EmitAsm("LDA", Mem(CallArgBase + 0));
            EmitAsm("BNE", Rel("__kq_fio_back_dec0"));
            EmitAsm("DEC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_back_dec0"));
            EmitAsm("DEC", Mem(CallArgBase + 0));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("BNE", Rel("__kq_fio_back_dec2"));
            EmitAsm("DEC", Mem(CallArgBase + 3));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_back_dec2"));
            EmitAsm("DEC", Mem(CallArgBase + 2));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", IndY(CallArgBase));
            EmitAsm("STA", IndY(CallArgBase + 2));
            EmitAsm("JSR", Abs("__kq_fds_copy_count"));
            EmitAsm("BNE", Rel("__kq_fio_backward"));
            EmitAsm("JMP", Abs("__kq_fio_load_ok"));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_forward"));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", IndY(CallArgBase));
            EmitAsm("STA", IndY(CallArgBase + 2));
            EmitAsm("INC", Mem(CallArgBase + 0));
            EmitAsm("BNE", Rel("__kq_fio_forward_inc0"));
            EmitAsm("INC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_forward_inc0"));
            EmitAsm("INC", Mem(CallArgBase + 2));
            EmitAsm("BNE", Rel("__kq_fio_forward_inc2"));
            EmitAsm("INC", Mem(CallArgBase + 3));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_forward_inc2"));
            EmitAsm("JSR", Abs("__kq_fds_copy_count"));
            EmitAsm("BNE", Rel("__kq_fio_forward"));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_load_ok"));
            EmitAsm("LDA", Imm(0));
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_load_return"));
            EmitAsm("RTS");
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_load_invalid"));
            EmitAsm("LDA", Imm(0xFF));
            EmitAsm("RTS");

Écrase, avec les octets d’un tampon CPU, un emplacement de sauvegarde PRG de taille fixe réservé en fin de face du disque. Le fichier conserve son identifiant, son nom et sa future adresse de chargement.

Syntaxe

u8 __fds_save_file(u8 id, const u8* src, u16 len);

Paramètres

id

Identifiant d’un fichier non destiné au démarrage, inclus dans le disque généré, de 0 à 254 ; l’exemple utilise 73. Il est distinct de la position physique du fichier. L’ID 255, les identifiants absents et les fichiers de démarrage sont refusés.

src

Début des données en RAM CPU, lisible sur len octets. Cette API ne sauvegarde pas directement la VRAM.

len

Nombre d’octets à sauvegarder ; il doit être égal à la longueur du fichier empaqueté. Si le jeu a moins de données, remplissez la partie inutilisée du tampon de sauvegarde avant l’appel.

Valeur renvoyée

Zéro en cas de succès ; sinon, l’erreur BIOS, par exemple une protection en écriture ou un échec de vérification après écriture. Renvoie 255 ($FF) sans appeler le BIOS si l’ID est invalide, si le fichier est de démarrage ou non PRG, s’il n’est pas le dernier de sa face, si la longueur diffère ou si la plage CPU est invalide.

Conditions et limites

Utilisez cette API avec --mapper=fds --fds-layout=fds32. Le manifeste --fds-meta définit les identifiants de fichiers, les adresses de chargement, les types, le statut de démarrage et l’ordre. Les adresses et tailles de transfert proviennent de l’image disque produite par la compilation ; cette API n’inspecte pas un disque quelconque inséré.

Le BIOS WriteFile masque logiquement les fichiers qui suivent la position d’écriture. Cette API n’accepte donc que le dernier fichier PRG non destiné au démarrage de chaque face. Elle n’ajoute pas de fichier et ne redimensionne pas l’emplacement. Celui-ci doit rester le dernier dans la disposition finale, y compris après l’ajout des aides au démarrage générées et des overlays automatiques.

Le compilateur distingue l’identifiant de fichier, le numéro d’en-tête et l’ordre physique. L’exemple a l’ID 73 et le numéro de manifeste 200, mais transmet la position 3 au BIOS. Les numéros de disque et de face proviennent aussi de la disposition résolue. N’utilisez pas cette API avec un disque dont la disposition a été modifiée indépendamment du manifeste.

Chaque tampon CPU doit tenir entièrement dans $0200–$07FF ou dans $6000–$DFFF. Les plages qui bouclent dans l’espace d’adressage et les destinations dans les registres d’E/S sont refusées. L’appelant doit aussi éviter tout chevauchement avec le code, l’OAM, les autres variables et les zones temporaires du compilateur. L’exemple utilise la banque 0 pour le code commun, $8000 pour la zone intermédiaire et deux tampons de quatre octets à $8500 et $8600.

Ces appels BIOS sont synchrones. Appelez-les depuis le code commun pour que le transfert n’écrase ni le code en cours d’exécution ni son adresse de retour ; ne les appelez pas depuis un gestionnaire d’interruption. Respectez les prérequis du BIOS pendant les E/S disque : arrêtez le rendu et la NMI, réglez l’incrément d’adresse PPU à un et désactivez les sources d’IRQ autres que le disque. La continuité du jeu ou de la musique pendant le transfert n’est pas garantie.

La capture utilise un programme de test original de la convention d’appel BIOS pour vérifier le code CPU compilé, le contenu des tampons, la sauvegarde suivie d’une relecture et chaque pixel affiché. Elle ne vérifie ni le véritable BIOS, ni les écritures sur disque physique, ni le CRC, ni la récupération après coupure de courant. Une exécution FDS ordinaire dans KUROSAKI ne suffit pas à établir le même comportement de sauvegarde.

Utilisez l’exemple avec fds_file_io_manifest.json et fds_file_io_payload.bin du même dossier. Le vérificateur ci-dessous génère un programme de test temporaire à partir de sources originales, puis le supprime. Aucun BIOS commercial n’est inclus, et ce programme de test n’est pas un BIOS destiné aux jeux ordinaires.

Convention d’appel du BIOS FDS

Exemple d’utilisation

#pragma fixed_bank 0
#include "fc_fds_scene.h"
void main(void) {
    u8 i;
    u8* data=(u8*)0x8500;
    u8* again=(u8*)0x8600;
    __irq_disable();__ppu_ctrl_set(0);__ppu_mask_set(0);
    // Keep rendering/NMI and non-disk IRQ sources disabled during disk I/O.
    *((u8*)0xFF)=0;*((u8*)0x4010)=0;*((u8*)0x4017)=0x40;*((u8*)0x4022)=0;
    fds_result[0]=__fds_load_file(73,data);
    fds_result[1]=data[0];fds_result[2]=data[3];
    for(i=0;i<4;i=i+1){data[i]=(i+1)*7;}
    fds_result[3]=__fds_save_file(73,data,4);
    fds_result[4]=__fds_load_file(73,again);
    fds_result[5]=again[0];fds_result[6]=again[3];
    // Check every returned byte, not only the displayed endpoints.
    for(i=0;i<4;i=i+1){if(again[i]!=(i+1)*7){fds_result[7]=1;}}
    fds_result[15]=165;
    m_init();m_text(2,2,"FDS LOAD / SAVE BUFFER");m_wait();
    m_text(2,5,"LOAD TO 8500 STATUS");fds_number(25,5,fds_result[0]);m_wait();
    m_text(2,7,"INITIAL FIRST/LAST");fds_number(21,7,fds_result[1]);fds_number(25,7,fds_result[2]);m_wait();
    m_text(2,9,"SAVE FILE 73 STATUS");fds_number(25,9,fds_result[3]);m_wait();
    m_text(2,11,"RELOAD TO 8600 STATUS");fds_number(25,11,fds_result[4]);m_wait();
    m_text(2,13,"SAVED FIRST / LAST");fds_number(21,13,fds_result[5]);fds_number(25,13,fds_result[6]);m_wait();
    m_text(2,15,"BYTE CHECK ERRORS");fds_number(25,15,fds_result[7]);m_wait();
    m_text(2,18,"STAGING 8000 / SIZE 4");m_wait();
    while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

LOAD, SAVE, RELOAD STATUS et BYTE CHECK ERRORS affichent tous 000. INITIAL FIRST/LAST affiche 011 et 044, premier et dernier des quatre octets chargés à $8500. L’exemple les remplace par 7, 14, 21 et 28, les sauvegarde puis les recharge à $8600 : SAVED FIRST / LAST affiche donc 007 et 028. STAGING 8000 / SIZE 4 indique l’adresse de chargement définie sur disque et la longueur du fichier. Le test indépendant vérifie également que l’ID 73 est sauvegardé dans le quatrième fichier physique, à la position 3 en comptant depuis zéro.

Programme d’exemple complet

fds_file_io_manifest.json

fds_file_io_payload.bin

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_file_io.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_file_io.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --fds-meta=.\kitaq-docs\samples\api-examples\fc\fds_file_io_manifest.json --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
python .\kitaq-docs\tools\check_fds_file_examples.py

Overwrite the final non-boot PRG slot on its side, preserving its ID/name/load
address. len must equal its packaged size; src must be a valid CPU RAM span.
The resolved physical ordinal selects the slot, independently of file ID.
Return 0, a BIOS error, or $FF before any write for an invalid slot/span/size.

EmitHelperStart("__fds_save_file");
            // Only a non-boot, final, fixed-size PRG slot can be overwritten without hiding later files.
            EmitAsm("JSR", Abs("__kq_fds_find_io"));
            EmitAsm("CMP", Imm(0));
            EmitAsm("BNE", Rel("__kq_fio_save_invalid"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 19));
            EmitAsm("AND", Imm(0xC0));
            EmitAsm("CMP", Imm(0x40));
            EmitAsm("BNE", Rel("__kq_fio_save_invalid"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 20));
            EmitAsm("BNE", Rel("__kq_fio_save_invalid"));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("CMP", Mem(_runtimeFdsFileHeaderAddress + 23));
            EmitAsm("BNE", Rel("__kq_fio_save_invalid"));
            EmitAsm("STA", Mem(CallArgBase + 10));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(CallArgBase + 8));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("CMP", Mem(_runtimeFdsFileHeaderAddress + 24));
            EmitAsm("BNE", Rel("__kq_fio_save_invalid"));
            EmitAsm("STA", Mem(CallArgBase + 11));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(CallArgBase + 9));
            EmitAsm("JSR", Abs("__kq_fds_check_span"));
            EmitAsm("CMP", Imm(0));
            EmitAsm("BNE", Rel("__kq_fio_save_invalid"));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 17));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 0));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 25));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 1));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 26));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 2));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 27));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 3));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 28));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 4));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 29));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 5));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 30));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 6));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 31));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 7));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 32));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 8));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 21));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 9));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 11));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 14));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 22));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 10));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 12));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 15));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 13));
            EmitAsm("STA", Mem(_runtimeFdsFileHeaderAddress + 16));
            EmitAsm("LDA", Mem(_runtimeFdsFileHeaderAddress + 18));
            EmitAsm("JSR", Mem(0xE239));
            _assembly.Add(Expr.Make(Tag.Word, string.Format("${0:X4}", _runtimeFdsFileHeaderAddress + 33)));
            _assembly.Add(Expr.Make(Tag.Word, string.Format("${0:X4}", _runtimeFdsFileHeaderAddress)));
            EmitAsm("RTS");
            _assembly.Add(Expr.Make(Tag.Label, "__kq_fio_save_invalid"));
            EmitAsm("LDA", Imm(0xFF));
            EmitAsm("RTS");

            // Enable wave-RAM writes, copy 64 source bytes, then clear the wave-write control register.

Renvoie la banque logique mémorisée comme résidente, sans lire le disque.

Syntaxe

u8 __fds_current_bank(void);

Valeur renvoyée

Valeur logicielle de résidence sur huit bits : 1 juste après le démarrage standard, ou 255 si elle est inconnue.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

Le démarrage FDS standard initialise la banque mémorisée à 1. __fds_load_bank() la met à jour après un chargement réussi. Les chargements bruts via __fds_load_file() ou __fds_load_overlay(), ainsi que les transferts de banque échoués, fixent cette valeur à 255 (inconnue). Aucun contenu mémoire n’est vérifié ; ne vous fiez pas à cette information après modification directe de la fenêtre. Une routine de réinitialisation personnalisée doit gérer elle-même l’initialisation.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    request_overlay=0;
    fds_result[0] = __fds_current_bank();
    fds_result[1] = __fds_is_bank_resident(1);
    fds_result[2] = __fds_is_bank_resident(2);
    fds_result[3] = __fds_overlay_function_count();
    if (request_overlay) {
        fds_result[4]=lesson_overlay_a(); fds_result[5]=lesson_overlay_b();
    }
    m_init();
    m_text(2,2,"FDS OVERLAY RECORDS"); m_wait();
    m_text(2,5,"CURRENT BANK"); m_put(25,5,'0'+fds_result[0]); m_wait();
    m_text(2,7,"BANK 1 RESIDENT"); m_put(25,7,'0'+fds_result[1]); m_wait();
    m_text(2,9,"BANK 2 RESIDENT"); m_put(25,9,'0'+fds_result[2]); m_wait();
    m_text(2,11,"OVERLAY FUNCTIONS"); m_put(25,11,'0'+fds_result[3]); m_wait();
    m_text(2,14,"NO OVERLAY LOAD TESTED"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

CURRENT BANK vaut 1, BANK 1 RESIDENT vaut 1, BANK 2 RESIDENT vaut 0 et OVERLAY FUNCTIONS vaut 2. Placer deux fonctions dans la banque 2 ne rend pas cette banque résidente au démarrage. Dans la compilation de vérification avec --fds-no-overlay-table, seule la dernière valeur devient zéro.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_residency.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_residency.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Return the software resident-bank byte, or FF after a failed bank transfer.
This is not a checksum of overlay memory.

case "__fds_current_bank":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Mem(_runtimeFdsResidentBankAddress));
                    return true;

Effectue un appel interbanque sans paramètre avec la forme propre au FDS. Le chargement et la restauration sont identiques à ceux de __fds_overlay_farcall().

Syntaxe

u8 __fds_farcall(u8 bank, u16 func);

Paramètres

bank

Expression représentant la banque. Elle est évaluée une fois avant l’appel, mais la banque réellement chargée est déterminée par l’emplacement de func après l’édition de liens. Cela n’appelle pas une adresse dans une banque arbitraire choisie à l’exécution. Passez une valeur correspondante, comme __bankof(func).

func

Nom d’une fonction déclarée sans paramètre. L’exemple passe u8 overlay_answer(void). Les adresses numériques, les pointeurs de fonction à l’exécution et les fonctions demandant des arguments sont refusés. Utilisez un appel ordinaire target(a, b) si des arguments sont nécessaires.

Valeur renvoyée

Résultat sur huit bits de la fonction cible. Si le chargement échoue mais que la banque précédente peut être restaurée, la cible n’est pas appelée et l’octet d’erreur de chargement est renvoyé à la place. Définissez une convention de résultat qui distingue une erreur d’un résultat normal.

Conditions et limites

Utilisez cette API avec --mapper=fds --fds-layout=fds32. La banque 0 contient le code commun à $A000–$DFFF. La banque 1 occupe $6000–$9FFF au démarrage ; les banques 2 et suivantes sont des overlays chargés dans cette même fenêtre de 16 Kio. Placez le code ou les données d’un overlay avec une directive telle que #pragma fixed_bank 2.

La banque 1 est restaurée depuis un fichier PRG de démarrage distinct de 16 384 octets à $6000. Sans manifeste, les fichiers par défaut ont l’ID 0 pour la banque 1, l’ID 1 pour le code commun et l’ID 2 pour CHR. Un manifeste personnalisé doit scinder le PRG de démarrage en fichiers de 16 384 octets à $6000 et $A000. Pour les banques à partir de 2, l’identifiant est --fds-overlay-start-id (32 par défaut) + numéro de banque − 2.

Lors d’un appel vers une autre banque, la banque précédente est mémorisée puis restaurée avant le retour. Les appels imbriqués suivent la même règle. Une restauration est également tentée après un transfert partiellement échoué. Si la restauration échoue elle-même, l’exécution s’arrête dans le code commun au lieu de revenir à du code écrasé. Les appels vers la banque commune ou la même banque évitent les transferts inutiles.

Les appels BIOS sont synchrones ; cette API ne fait pas avancer la boucle de jeu une fois par image pendant un chargement. Utilisez-la depuis le code de contrôle ordinaire de la banque commune, et non depuis un gestionnaire d’interruption. La continuité de l’affichage et de l’audio ainsi que la coexistence avec le véritable BIOS doivent être vérifiées séparément.

Ces captures utilisent un programme de test original de la convention d’appel LoadFiles pour vérifier le code CPU compilé, les transferts mémoire et chaque pixel affiché. Elles ne vérifient ni le véritable BIOS, ni la durée des transferts disque, ni le CRC, ni le démarrage sur matériel réel. Le modèle de contrôleur FDS de KUROSAKI est partiel ; une exécution ordinaire sans ce programme de test ne prouve pas les mêmes résultats de transfert.

La première commande de compilation ci-dessous construit l’exemple téléchargeable. Le vérificateur Python compile les cinq leçons avec et sans optimisation, puis les vérifie dans KUROSAKI. Il crée et supprime un programme de test temporaire à partir de scripts/fds_abi_fixture.py ; ces vérifications ne nécessitent aucun BIOS externe. Ce programme de test n’est pas un BIOS pour les jeux ordinaires.

Exemple d’utilisation

#pragma fixed_bank 0
#include "fc_fds_scene.h"
u8 choose_overlay(void){fds_result[2]++;return 2;}
#pragma fixed_bank 2
u8 overlay_answer(void){fds_result[1]++;fds_result[3]=__fds_current_bank();return 42;}
#pragma fixed_bank 0
void main(void) {
    __irq_disable();fds_result[1]=0;fds_result[2]=0;
    fds_result[0]=__fds_farcall(choose_overlay(),overlay_answer);
    fds_result[4]=__fds_current_bank();fds_result[15]=165;
    fds_call_screen();while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Avec le programme de test original de l’ABI LoadFiles, RETURN VALUE vaut 042 ; CALLBACK COUNT et BANK EXPR COUNT valent chacun 001 ; BANK IN CALLBACK vaut 002 et BANK AFTER RETURN vaut 001. La fonction et l’expression de banque ont été exécutées une fois chacune, et la banque 1 a été restaurée après l’appel à la banque 2. Ce n’est pas une capture d’un véritable test de transfert disque.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_farcall.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_farcall.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --fds-overlay-trim --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
python .\kitaq-docs\tools\check_fds_load_examples.py

Same named, zero-argument dispatch as __fds_overlay_farcall; evaluate bank once.

if (string.Equals(funcName, "__fds_overlay_farcall", StringComparison.Ordinal) ||
                string.Equals(funcName, "__fds_farcall", StringComparison.Ordinal))
            {
                // FDS overlay dispatch requires the configured FDS RAM layout and a named function target.
                Expr[] farArgs = args ?? Array.Empty<Expr>();
                if (farArgs.Length != 2)
                {
                    Program.Error("error KQFC2512: {0}(bank, func) expects exactly 2 arguments.", funcName);
                    return;
                }
                string targetName;
                if (!farArgs[1].Match(Tag.Name, out targetName))
                {
                    Program.Error("error KQFC2513: {0}(bank, func) requires the 2nd argument to be a function name.", funcName);
                    return;
                }
                if (!Program.NesMapperProfile.HasFds || !Program.FdsPrgRamLayoutEnabled)
                {
                    Program.Error("error KQFC2514: {0} requires --mapper=fds with --fds-layout=fds32.", funcName);
                    return;
                }
                // Like ordinary __farcall, this entry supplies no callback arguments.
                // Validate before emitting code so a data symbol cannot become a JSR target.
                if (!_functionParameters.TryGetValue(targetName, out FieldInfo[] fdsParameters))
                {
                    Program.Error("error KQFC2610: {0} requires a declared function name; use an ordinary typed call for a function pointer.", funcName);
                    return;
                }
                if (fdsParameters.Length != 0)
                {
                    Program.Error("error KQFC2610: {0} requires a callback with no parameters.", funcName);
                    return;
                }
                // Evaluate the bank expression exactly once, even for a safe direct call.
                // The named target's linked placement determines the dispatched bank.
                EmitLoadValue(farArgs[0], ctx, 1);
                int callerBank = ctx == null ? 0 : ctx.Bank;
                int calleeBank = GetFunctionBank(targetName);
                if (ShouldUseFdsOverlayThunk(callerBank, calleeBank))
                {
                    string directFdsThunkName = EnsureFdsOverlayThunk(targetName, calleeBank);
                    EmitAsm("JSR", Abs(directFdsThunkName));
                    RecordCallEdge(targetName, calleeBank, "fds_overlay_thunk", viaThunk: true, viaFarcall: true);
                    return;
                }
                if (calleeBank == 0 || calleeBank == callerBank)
                {
                    EmitAsm("JSR", Abs(targetName));
                    RecordCallEdge(targetName, calleeBank, "direct", viaThunk: false, viaFarcall: true);
                    return;
                }
                string fdsThunkName = EnsureFdsOverlayThunk(targetName, calleeBank);
                EmitAsm("JSR", Abs(fdsThunkName));
                RecordCallEdge(targetName, calleeBank, "fds_overlay_thunk", viaThunk: true, viaFarcall: true);
                return;
            }

Compare la banque demandée à la valeur de résidence mémorisée. Peut aider à décider si un chargement est nécessaire, mais ne l’effectue pas.

Syntaxe

u8 __fds_is_bank_resident(u8 bank);

Paramètres

bank

Numéro de banque logique à comparer. Le démarrage standard mémorise 1 ; les overlays générés utilisent 2 et plus. La banque 0 contient le code commun et n’est pas la valeur initiale de cet enregistrement de résidence.

Valeur renvoyée

1 si une banque valide correspond à la valeur mémorisée, sinon 0. La banque 255 (inconnue) renvoie toujours zéro, même lorsque la valeur mémorisée est 255.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

Le démarrage FDS standard initialise la banque mémorisée à 1. __fds_load_bank() la met à jour après un chargement réussi. Les chargements bruts via __fds_load_file() ou __fds_load_overlay(), ainsi que les transferts de banque échoués, fixent cette valeur à 255 (inconnue). Aucun contenu mémoire n’est vérifié ; ne vous fiez pas à cette information après modification directe de la fenêtre. Une routine de réinitialisation personnalisée doit gérer elle-même l’initialisation.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    request_overlay=0;
    fds_result[0] = __fds_current_bank();
    fds_result[1] = __fds_is_bank_resident(1);
    fds_result[2] = __fds_is_bank_resident(2);
    fds_result[3] = __fds_overlay_function_count();
    if (request_overlay) {
        fds_result[4]=lesson_overlay_a(); fds_result[5]=lesson_overlay_b();
    }
    m_init();
    m_text(2,2,"FDS OVERLAY RECORDS"); m_wait();
    m_text(2,5,"CURRENT BANK"); m_put(25,5,'0'+fds_result[0]); m_wait();
    m_text(2,7,"BANK 1 RESIDENT"); m_put(25,7,'0'+fds_result[1]); m_wait();
    m_text(2,9,"BANK 2 RESIDENT"); m_put(25,9,'0'+fds_result[2]); m_wait();
    m_text(2,11,"OVERLAY FUNCTIONS"); m_put(25,11,'0'+fds_result[3]); m_wait();
    m_text(2,14,"NO OVERLAY LOAD TESTED"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

CURRENT BANK vaut 1, BANK 1 RESIDENT vaut 1, BANK 2 RESIDENT vaut 0 et OVERLAY FUNCTIONS vaut 2. Placer deux fonctions dans la banque 2 ne rend pas cette banque résidente au démarrage. Dans la compilation de vérification avec --fds-no-overlay-table, seule la dernière valeur devient zéro.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_residency.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_residency.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Compare a valid bank with the software resident-bank byte; FF (unknown) never matches.

EmitHelperStart("__fds_is_bank_resident");
            string fdsResidentYes = NewGeneratedLabel("fds_resident_yes");
            string fdsResidentNo = NewGeneratedLabel("fds_resident_no");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("CMP", Imm(0xFF));
            EmitAsm("BEQ", Rel(fdsResidentNo));
            EmitAsm("CMP", Mem(_runtimeFdsResidentBankAddress));
            EmitAsm("BEQ", Rel(fdsResidentYes));
            _assembly.Add(Expr.Make(Tag.Label, fdsResidentNo));
            EmitAsm("LDA", Imm(0));
            EmitAsm("RTS");
            _assembly.Add(Expr.Make(Tag.Label, fdsResidentYes));
            EmitAsm("LDA", Imm(1));
            EmitAsm("RTS");

            // Query file existence in the compiled metadata table.

Convertit une banque logique en identifiant de fichier et charge la fenêtre d’overlay $6000–$9FFF, puis mémorise cette banque comme résidente.

Syntaxe

u8 __fds_load_bank(u8 bank);

Paramètres

bank

Banque logique à charger, de 1 à 254. La banque 0 est du code commun, pas une fenêtre chargeable ; 255 est réservé à une résidence inconnue. À partir de la banque 2, l’identifiant de fichier calculé doit aussi tenir dans 0..254.

Valeur renvoyée

Zéro en cas de succès. Renvoie 255 pour les banques 0 ou 255, un dépassement de l’identifiant de fichier ou une banque 1 sans fichier de restauration. Un transfert BIOS échoué renvoie son octet d’erreur. Une erreur d’argument avant le transfert conserve la banque mémorisée ; un échec de transfert BIOS la marque 255 (inconnue).

Conditions et limites

Utilisez cette API avec --mapper=fds --fds-layout=fds32. La banque 0 contient le code commun à $A000–$DFFF. La banque 1 occupe $6000–$9FFF au démarrage ; les banques 2 et suivantes sont des overlays chargés dans cette même fenêtre de 16 Kio. Placez le code ou les données d’un overlay avec une directive telle que #pragma fixed_bank 2.

La banque 1 est restaurée depuis un fichier PRG de démarrage distinct de 16 384 octets à $6000. Sans manifeste, les fichiers par défaut ont l’ID 0 pour la banque 1, l’ID 1 pour le code commun et l’ID 2 pour CHR. Un manifeste personnalisé doit scinder le PRG de démarrage en fichiers de 16 384 octets à $6000 et $A000. Pour les banques à partir de 2, l’identifiant est --fds-overlay-start-id (32 par défaut) + numéro de banque − 2.

Avec la vérification de résidence par défaut, une banque déjà enregistrée renvoie zéro sans lecture disque. --fds-no-overlay-guard désactive ce raccourci dans __fds_load_bank(). Un chargement réussi mémorise la banque demandée. Cette information ne valide pas le contenu de la mémoire.

Charger une autre banque directement depuis du code dans la fenêtre $6000–$9FFF peut écraser la fonction en cours ou son adresse de retour. Cet exemple place l’appelant et le code d’affichage dans #pragma fixed_bank 0. Pour appeler une fonction d’une autre banque puis revenir, utilisez __fds_overlay_farcall() ou un appel de fonction typé ordinaire.

Les appels BIOS sont synchrones ; cette API ne fait pas avancer la boucle de jeu une fois par image pendant un chargement. Utilisez-la depuis le code de contrôle ordinaire de la banque commune, et non depuis un gestionnaire d’interruption. La continuité de l’affichage et de l’audio ainsi que la coexistence avec le véritable BIOS doivent être vérifiées séparément.

Ces captures utilisent un programme de test original de la convention d’appel LoadFiles pour vérifier le code CPU compilé, les transferts mémoire et chaque pixel affiché. Elles ne vérifient ni le véritable BIOS, ni la durée des transferts disque, ni le CRC, ni le démarrage sur matériel réel. Le modèle de contrôleur FDS de KUROSAKI est partiel ; une exécution ordinaire sans ce programme de test ne prouve pas les mêmes résultats de transfert.

La première commande de compilation ci-dessous construit l’exemple téléchargeable. Le vérificateur Python compile les cinq leçons avec et sans optimisation, puis les vérifie dans KUROSAKI. Il crée et supprime un programme de test temporaire à partir de scripts/fds_abi_fixture.py ; ces vérifications ne nécessitent aucun BIOS externe. Ce programme de test n’est pas un BIOS pour les jeux ordinaires.

Exemple d’utilisation

#pragma fixed_bank 0
#include "fc_fds_scene.h"
#pragma fixed_bank 2
__prg_rom u8 bank_payload[4]={11,22,33,44};
#pragma fixed_bank 0
void main(void) {
    __irq_disable();
    fds_result[0]=__fds_load_bank(2);
    fds_result[1]=__fds_current_bank();
    fds_result[2]=__fds_require_bank(2);
    fds_result[3]=bank_payload[0];fds_result[4]=bank_payload[3];
    fds_result[5]=nes_fds_load_bank(1);
    fds_result[6]=__fds_current_bank();
    fds_result[7]=__fds_require_bank(1);
    fds_result[8]=__fds_load_bank(0);
    fds_result[9]=__fds_load_bank(255);
    fds_result[15]=165;
    m_init();m_text(2,2,"FDS DATA WINDOW");m_wait();
    m_text(2,5,"LOAD BANK 2 STATUS");fds_number(25,5,fds_result[0]);m_wait();
    m_text(2,7,"FIRST / LAST BYTE");fds_number(21,7,fds_result[3]);fds_number(25,7,fds_result[4]);m_wait();
    m_text(2,9,"REQUIRE SAME BANK");fds_number(25,9,fds_result[2]);m_wait();
    m_text(2,11,"RESTORE BANK 1");fds_number(25,11,fds_result[5]);m_wait();
    m_text(2,13,"RESIDENT BANK");fds_number(25,13,fds_result[6]);m_wait();
    m_text(2,16,"INVALID BANKS 0 / 255");m_wait();
    fds_number(2,18,fds_result[8]);fds_number(8,18,fds_result[9]);m_wait();
    while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Avec le programme de test original de l’ABI LoadFiles, LOAD BANK 2 STATUS, REQUIRE SAME BANK et RESTORE BANK 1 valent tous 000. FIRST / LAST BYTE affiche 011 et 044, issus des quatre octets transférés ; RESIDENT BANK vaut 001 après restauration. Les banques invalides 0 et 255 renvoient chacune 255. Demander la même banque ne provoque aucun chargement supplémentaire : les requêtes de fichiers vérifiées sont 32, puis 0.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_bank_load.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_bank_load.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --fds-overlay-trim --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
python .\kitaq-docs\tools\check_fds_load_examples.py

Load logical bank 1 from its separate boot file, or bank 2+ from overlay-start-id+(bank-2).
Return zero on success, FF for invalid/unavailable mappings, or the BIOS error.
A failed BIOS transfer marks residency FF (unknown); a matching valid guard can skip loading.

EmitHelperStart("__fds_load_bank");
            string fdsLoadBankLoad = NewGeneratedLabel("fds_load_bank_load");
            string fdsLoadBankOverlay = NewGeneratedLabel("fds_load_bank_overlay");
            string fdsLoadBankCall = NewGeneratedLabel("fds_load_bank_call");
            string fdsLoadBankDone = NewGeneratedLabel("fds_load_bank_done");
            string fdsLoadBankPopInvalid = NewGeneratedLabel("fds_load_bank_pop_invalid");
            string fdsLoadBankInvalid = NewGeneratedLabel("fds_load_bank_invalid");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("CMP", Imm(1));
            EmitAsm("BCC", Rel(fdsLoadBankInvalid));
            EmitAsm("CMP", Imm(0xFF));
            EmitAsm("BEQ", Rel(fdsLoadBankInvalid));
            if (Program.FdsOverlayResidencyGuardEnabled)
            {
                EmitAsm("CMP", Mem(_runtimeFdsResidentBankAddress));
                EmitAsm("BNE", Rel(fdsLoadBankLoad));
                EmitAsm("LDA", Imm(0));
                EmitAsm("RTS");
                _assembly.Add(Expr.Make(Tag.Label, fdsLoadBankLoad));
            }
            EmitAsm("PHA");
            EmitAsm("CMP", Imm(1));
            EmitAsm("BNE", Rel(fdsLoadBankOverlay));
            EmitAsm("LDA", Abs("__kq_fds_boot_bank_file_id"));
            EmitAsm("CMP", Imm(0xFF));
            EmitAsm("BEQ", Rel(fdsLoadBankPopInvalid));
            EmitAsm("JMP", Abs(fdsLoadBankCall));
            _assembly.Add(Expr.Make(Tag.Label, fdsLoadBankOverlay));
            EmitAsm("SEC");
            EmitAsm("SBC", Imm(2));
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(Program.FdsOverlayStartId & 0xFF));
            EmitAsm("BCS", Rel(fdsLoadBankPopInvalid));
            EmitAsm("CMP", Imm(0xFF));
            EmitAsm("BEQ", Rel(fdsLoadBankPopInvalid));
            _assembly.Add(Expr.Make(Tag.Label, fdsLoadBankCall));
            EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__fds_load_overlay"));
            EmitAsm("TAX");
            EmitAsm("PLA");
            EmitAsm("CPX", Imm(0));
            EmitAsm("BEQ", Rel(fdsLoadBankDone));
            // A failed BIOS transfer may have overwritten part of the window.
            // Mark it unknown so a subsequent restore cannot be skipped by the guard.
            EmitAsm("LDA", Imm(0xFF));
            _assembly.Add(Expr.Make(Tag.Label, fdsLoadBankDone));
            EmitAsm("STA", Mem(_runtimeFdsResidentBankAddress));
            EmitAsm("STA", Mem(_runtimeCurrentBankAddress));
            EmitAsm("TXA");
            EmitAsm("RTS");
            _assembly.Add(Expr.Make(Tag.Label, fdsLoadBankPopInvalid));
            EmitAsm("PLA");
            _assembly.Add(Expr.Make(Tag.Label, fdsLoadBankInvalid));
            EmitAsm("LDA", Imm(0xFF));
            EmitAsm("RTS");

            // Return success for the recorded resident bank, otherwise dispatch a bank load.

Appelle BIOS LoadFiles avec un identifiant de fichier disque plutôt qu’un numéro de banque logique. L’en-tête du fichier détermine la destination.

Syntaxe

u8 __fds_load_overlay(u8 id);

Paramètres

id

Identifiant de fichier disque, de 0 à 254. Ne passez pas 255 : il termine la liste de fichiers du BIOS. Dans la disposition par défaut, l’ID 32 contient la banque 2.

Valeur renvoyée

Octet d’erreur BIOS, zéro indiquant un succès. Après un succès comme après un échec, la résidence est marquée 255 (inconnue) ; un identifiant de fichier seul ne définit pas le mappage d’une banque logique.

Conditions et limites

Utilisez cette API avec --mapper=fds --fds-layout=fds32. La banque 0 contient le code commun à $A000–$DFFF. La banque 1 occupe $6000–$9FFF au démarrage ; les banques 2 et suivantes sont des overlays chargés dans cette même fenêtre de 16 Kio. Placez le code ou les données d’un overlay avec une directive telle que #pragma fixed_bank 2.

Construit une liste contenant l’ID demandé et le terminateur 255. Vérifiez la destination du manifeste pour éviter d’écraser le code commun ou en cours d’exécution. Préférez __fds_load_bank() pour les overlays logiques : cette fonction gère la résidence.

Charger une autre banque directement depuis du code dans la fenêtre $6000–$9FFF peut écraser la fonction en cours ou son adresse de retour. Cet exemple place l’appelant et le code d’affichage dans #pragma fixed_bank 0. Pour appeler une fonction d’une autre banque puis revenir, utilisez __fds_overlay_farcall() ou un appel de fonction typé ordinaire.

Les appels BIOS sont synchrones ; cette API ne fait pas avancer la boucle de jeu une fois par image pendant un chargement. Utilisez-la depuis le code de contrôle ordinaire de la banque commune, et non depuis un gestionnaire d’interruption. La continuité de l’affichage et de l’audio ainsi que la coexistence avec le véritable BIOS doivent être vérifiées séparément.

Ces captures utilisent un programme de test original de la convention d’appel LoadFiles pour vérifier le code CPU compilé, les transferts mémoire et chaque pixel affiché. Elles ne vérifient ni le véritable BIOS, ni la durée des transferts disque, ni le CRC, ni le démarrage sur matériel réel. Le modèle de contrôleur FDS de KUROSAKI est partiel ; une exécution ordinaire sans ce programme de test ne prouve pas les mêmes résultats de transfert.

La première commande de compilation ci-dessous construit l’exemple téléchargeable. Le vérificateur Python compile les cinq leçons avec et sans optimisation, puis les vérifie dans KUROSAKI. Il crée et supprime un programme de test temporaire à partir de scripts/fds_abi_fixture.py ; ces vérifications ne nécessitent aucun BIOS externe. Ce programme de test n’est pas un BIOS pour les jeux ordinaires.

Exemple d’utilisation

#pragma fixed_bank 0
#include "fc_fds_scene.h"
#pragma fixed_bank 2
__prg_rom u8 raw_payload[4]={11,22,33,44};
#pragma fixed_bank 0
void main(void) {
    __irq_disable();
    fds_result[0]=__fds_load_overlay(32);
    fds_result[1]=__fds_current_bank();
    fds_result[2]=__fds_is_bank_resident(1);
    fds_result[3]=raw_payload[0];fds_result[4]=raw_payload[3];
    fds_result[5]=__fds_require_bank(1);
    fds_result[6]=__fds_current_bank();
    fds_result[15]=165;
    m_init();m_text(2,2,"FDS RAW FILE-ID LOAD");m_wait();
    m_text(2,5,"FILE 32 LOAD STATUS");fds_number(25,5,fds_result[0]);m_wait();
    m_text(2,7,"FIRST / LAST BYTE");fds_number(21,7,fds_result[3]);fds_number(25,7,fds_result[4]);m_wait();
    m_text(2,9,"UNKNOWN BANK RECORD");fds_number(25,9,fds_result[1]);m_wait();
    m_text(2,11,"IS BANK 1 RESIDENT");fds_number(25,11,fds_result[2]);m_wait();
    m_text(2,13,"REQUIRE BANK 1");fds_number(25,13,fds_result[5]);m_wait();
    m_text(2,15,"RESIDENT AFTER RELOAD");fds_number(25,15,fds_result[6]);m_wait();
    while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Avec le programme de test original de l’ABI LoadFiles, FILE 32 LOAD STATUS vaut 000 et les octets aux extrémités des données transférées valent 011 et 044. Après le chargement brut, UNKNOWN BANK RECORD vaut 255 et IS BANK 1 RESIDENT vaut 000. REQUIRE BANK 1 réussit avec 000, puis RESIDENT AFTER RELOAD vaut 001. Cela distingue le chargement par identifiant de fichier de la gestion d’une banque logique.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_raw_overlay.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_raw_overlay.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --fds-overlay-trim --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
python .\kitaq-docs\tools\check_fds_load_examples.py

Load disk file id through BIOS, return its error byte and mark bank residency FF (unknown).

EmitHelperStart("__fds_load_overlay");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeFdsLoadListAddress));
            EmitAsm("LDA", Imm(0xFF));
            EmitAsm("STA", Mem(_runtimeFdsLoadListAddress + 1));
            EmitAsm("JSR", Mem(0xE1F8));
            _assembly.Add(Expr.Make(Tag.Word, "__kq_fds_disk_id_wildcard"));
            _assembly.Add(Expr.Make(Tag.Word, string.Format("${0:X4}", _runtimeFdsLoadListAddress)));
            // A raw file load can replace any part of the switchable window.
            // Only the bank-aware wrapper may establish a known resident bank.
            EmitAsm("TAX");
            EmitAsm("LDA", Imm(0xFF));
            EmitAsm("STA", Mem(_runtimeFdsResidentBankAddress));
            EmitAsm("STA", Mem(_runtimeCurrentBankAddress));
            EmitAsm("TXA");
            EmitAsm("RTS");

            // Restore bank 1 from its separate boot file; map banks 2+ to overlay
            // IDs. Keep the requested bank on the CPU stack across the BIOS call.

Appelle une fonction sans paramètre dans un overlay et restaure la banque précédente avant le retour.

Syntaxe

u8 __fds_overlay_farcall(u8 bank, u16 func);

Paramètres

bank

Expression représentant la banque. Elle est évaluée une fois avant l’appel, mais la banque réellement chargée est déterminée par l’emplacement de func après l’édition de liens. Cela n’appelle pas une adresse dans une banque arbitraire choisie à l’exécution. Passez une valeur correspondante, comme __bankof(func).

func

Nom d’une fonction déclarée sans paramètre. L’exemple passe u8 overlay_answer(void). Les adresses numériques, les pointeurs de fonction à l’exécution et les fonctions demandant des arguments sont refusés. Utilisez un appel ordinaire target(a, b) si des arguments sont nécessaires.

Valeur renvoyée

Résultat sur huit bits de la fonction cible. Si le chargement échoue mais que la banque précédente peut être restaurée, la cible n’est pas appelée et l’octet d’erreur de chargement est renvoyé à la place. Définissez une convention de résultat qui distingue une erreur d’un résultat normal.

Conditions et limites

Utilisez cette API avec --mapper=fds --fds-layout=fds32. La banque 0 contient le code commun à $A000–$DFFF. La banque 1 occupe $6000–$9FFF au démarrage ; les banques 2 et suivantes sont des overlays chargés dans cette même fenêtre de 16 Kio. Placez le code ou les données d’un overlay avec une directive telle que #pragma fixed_bank 2.

La banque 1 est restaurée depuis un fichier PRG de démarrage distinct de 16 384 octets à $6000. Sans manifeste, les fichiers par défaut ont l’ID 0 pour la banque 1, l’ID 1 pour le code commun et l’ID 2 pour CHR. Un manifeste personnalisé doit scinder le PRG de démarrage en fichiers de 16 384 octets à $6000 et $A000. Pour les banques à partir de 2, l’identifiant est --fds-overlay-start-id (32 par défaut) + numéro de banque − 2.

Lors d’un appel vers une autre banque, la banque précédente est mémorisée puis restaurée avant le retour. Les appels imbriqués suivent la même règle. Une restauration est également tentée après un transfert partiellement échoué. Si la restauration échoue elle-même, l’exécution s’arrête dans le code commun au lieu de revenir à du code écrasé. Les appels vers la banque commune ou la même banque évitent les transferts inutiles.

Les appels BIOS sont synchrones ; cette API ne fait pas avancer la boucle de jeu une fois par image pendant un chargement. Utilisez-la depuis le code de contrôle ordinaire de la banque commune, et non depuis un gestionnaire d’interruption. La continuité de l’affichage et de l’audio ainsi que la coexistence avec le véritable BIOS doivent être vérifiées séparément.

Ces captures utilisent un programme de test original de la convention d’appel LoadFiles pour vérifier le code CPU compilé, les transferts mémoire et chaque pixel affiché. Elles ne vérifient ni le véritable BIOS, ni la durée des transferts disque, ni le CRC, ni le démarrage sur matériel réel. Le modèle de contrôleur FDS de KUROSAKI est partiel ; une exécution ordinaire sans ce programme de test ne prouve pas les mêmes résultats de transfert.

La première commande de compilation ci-dessous construit l’exemple téléchargeable. Le vérificateur Python compile les cinq leçons avec et sans optimisation, puis les vérifie dans KUROSAKI. Il crée et supprime un programme de test temporaire à partir de scripts/fds_abi_fixture.py ; ces vérifications ne nécessitent aucun BIOS externe. Ce programme de test n’est pas un BIOS pour les jeux ordinaires.

Exemple d’utilisation

#pragma fixed_bank 0
#include "fc_fds_scene.h"
u8 choose_overlay(void){fds_result[2]++;return 2;}
#pragma fixed_bank 2
u8 overlay_answer(void){fds_result[1]++;fds_result[3]=__fds_current_bank();return 42;}
#pragma fixed_bank 0
void main(void) {
    __irq_disable();fds_result[1]=0;fds_result[2]=0;
    fds_result[0]=__fds_overlay_farcall(choose_overlay(),overlay_answer);
    fds_result[4]=__fds_current_bank();fds_result[15]=165;
    fds_call_screen();while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Avec le programme de test original de l’ABI LoadFiles, RETURN VALUE vaut 042 ; CALLBACK COUNT et BANK EXPR COUNT valent chacun 001 ; BANK IN CALLBACK vaut 002 et BANK AFTER RETURN vaut 001. La fonction et l’expression de banque ont été exécutées une fois chacune, et la banque 1 a été restaurée après l’appel à la banque 2. Ce n’est pas une capture d’un véritable test de transfert disque.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_overlay_call.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_overlay_call.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --fds-overlay-trim --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
python .\kitaq-docs\tools\check_fds_load_examples.py

Evaluate bank once and call the named zero-argument function using its linked bank.
Restore the caller window before returning; restoration failure stops in common code.

if (string.Equals(funcName, "__fds_overlay_farcall", StringComparison.Ordinal) ||
                string.Equals(funcName, "__fds_farcall", StringComparison.Ordinal))
            {
                // FDS overlay dispatch requires the configured FDS RAM layout and a named function target.
                Expr[] farArgs = args ?? Array.Empty<Expr>();
                if (farArgs.Length != 2)
                {
                    Program.Error("error KQFC2512: {0}(bank, func) expects exactly 2 arguments.", funcName);
                    return;
                }
                string targetName;
                if (!farArgs[1].Match(Tag.Name, out targetName))
                {
                    Program.Error("error KQFC2513: {0}(bank, func) requires the 2nd argument to be a function name.", funcName);
                    return;
                }
                if (!Program.NesMapperProfile.HasFds || !Program.FdsPrgRamLayoutEnabled)
                {
                    Program.Error("error KQFC2514: {0} requires --mapper=fds with --fds-layout=fds32.", funcName);
                    return;
                }
                // Like ordinary __farcall, this entry supplies no callback arguments.
                // Validate before emitting code so a data symbol cannot become a JSR target.
                if (!_functionParameters.TryGetValue(targetName, out FieldInfo[] fdsParameters))
                {
                    Program.Error("error KQFC2610: {0} requires a declared function name; use an ordinary typed call for a function pointer.", funcName);
                    return;
                }
                if (fdsParameters.Length != 0)
                {
                    Program.Error("error KQFC2610: {0} requires a callback with no parameters.", funcName);
                    return;
                }
                // Evaluate the bank expression exactly once, even for a safe direct call.
                // The named target's linked placement determines the dispatched bank.
                EmitLoadValue(farArgs[0], ctx, 1);
                int callerBank = ctx == null ? 0 : ctx.Bank;
                int calleeBank = GetFunctionBank(targetName);
                if (ShouldUseFdsOverlayThunk(callerBank, calleeBank))
                {
                    string directFdsThunkName = EnsureFdsOverlayThunk(targetName, calleeBank);
                    EmitAsm("JSR", Abs(directFdsThunkName));
                    RecordCallEdge(targetName, calleeBank, "fds_overlay_thunk", viaThunk: true, viaFarcall: true);
                    return;
                }
                if (calleeBank == 0 || calleeBank == callerBank)
                {
                    EmitAsm("JSR", Abs(targetName));
                    RecordCallEdge(targetName, calleeBank, "direct", viaThunk: false, viaFarcall: true);
                    return;
                }
                string fdsThunkName = EnsureFdsOverlayThunk(targetName, calleeBank);
                EmitAsm("JSR", Abs(fdsThunkName));
                RecordCallEdge(targetName, calleeBank, "fds_overlay_thunk", viaThunk: true, viaFarcall: true);
                return;
            }

Renvoie le nombre de fonctions placées par l’éditeur de liens dans les banques d’overlay à partir de 2. Ce n’est ni un nombre de fonctions résidentes ni un nombre de fichiers.

Syntaxe

u8 __fds_overlay_function_count(void);

Valeur renvoyée

Octet de nombre placé en tête de table, de 0 à 255. Vaut zéro s’il n’y a aucune fonction d’overlay ou si --fds-no-overlay-table est utilisé. Plus de 255 entrées sont refusées avec KQFC2511.

Conditions et limites

Compilez avec --mapper=fds. Pour un mapper de cartouche, appeler une fonction réservée au FDS autre que __fds_available est refusé avec KQFC2420.

La génération de code crée un emplacement provisoire nul ; l’édition de liens FDS native le remplace par la table après placement des banques et adresses. L’exemple place deux fonctions dans la banque 2 sans les appeler. Les données initiales de --fds-layout=legacy ne constituent pas un décompte des fonctions d’overlay.

La capture utilise le chargement direct des fichiers de démarrage du disque en RAM par KUROSAKI. Cet exemple n’appelle aucune routine BIOS et ne vérifie ni les transferts de fichiers, ni le changement de disque, ni le démarrage sur matériel réel. Le micrologiciel de test vide n’est pas un BIOS de remplacement. L’exemple utilise la NMI pour l’affichage et désactive les IRQ masquables, inutiles à ces requêtes.

L’exemple de compilation produit un .fds à disposition native, sans les fichiers de démarrage supplémentaires de l’écran d’approbation. Cette configuration sert à vérifier le démarrage direct de KUROSAKI ; la procédure de démarrage d’une disquette sur matériel réel doit être validée séparément.

Exemple d’utilisation

void main(void) {
    // These BIOS-free queries need NMI for display, but no maskable IRQ.
    __irq_disable();
    request_overlay=0;
    fds_result[0] = __fds_current_bank();
    fds_result[1] = __fds_is_bank_resident(1);
    fds_result[2] = __fds_is_bank_resident(2);
    fds_result[3] = __fds_overlay_function_count();
    if (request_overlay) {
        fds_result[4]=lesson_overlay_a(); fds_result[5]=lesson_overlay_b();
    }
    m_init();
    m_text(2,2,"FDS OVERLAY RECORDS"); m_wait();
    m_text(2,5,"CURRENT BANK"); m_put(25,5,'0'+fds_result[0]); m_wait();
    m_text(2,7,"BANK 1 RESIDENT"); m_put(25,7,'0'+fds_result[1]); m_wait();
    m_text(2,9,"BANK 2 RESIDENT"); m_put(25,9,'0'+fds_result[2]); m_wait();
    m_text(2,11,"OVERLAY FUNCTIONS"); m_put(25,11,'0'+fds_result[3]); m_wait();
    m_text(2,14,"NO OVERLAY LOAD TESTED"); m_wait();
    while (1) { m_wait(); }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

CURRENT BANK vaut 1, BANK 1 RESIDENT vaut 1, BANK 2 RESIDENT vaut 0 et OVERLAY FUNCTIONS vaut 2. Placer deux fonctions dans la banque 2 ne rend pas cette banque résidente au démarrage. Dans la compilation de vérification avec --fds-no-overlay-table, seule la dernière valeur devient zéro.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_residency.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_residency.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Return the linker-generated overlay-function count; zero if the table is disabled.

case "__fds_overlay_function_count":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Abs("__kq_fds_overlay_function_table"));
                    return true;

Charge une banque uniquement si elle n’est pas déjà mémorisée comme résidente. Appelez cette fonction avant d’accéder à une ressource pour éviter un transfert inutile si elle est déjà disponible.

Syntaxe

u8 __fds_require_bank(u8 bank);

Paramètres

bank

Banque logique à charger, de 1 à 254. La banque 0 est du code commun, pas une fenêtre chargeable ; 255 est réservé à une résidence inconnue. À partir de la banque 2, l’identifiant de fichier calculé doit aussi tenir dans 0..254.

Valeur renvoyée

Zéro en cas de succès. Renvoie 255 pour les banques 0 ou 255, un dépassement de l’identifiant de fichier ou une banque 1 sans fichier de restauration. Un transfert BIOS échoué renvoie son octet d’erreur. Une erreur d’argument avant le transfert conserve la banque mémorisée ; un échec de transfert BIOS la marque 255 (inconnue).

Conditions et limites

Utilisez cette API avec --mapper=fds --fds-layout=fds32. La banque 0 contient le code commun à $A000–$DFFF. La banque 1 occupe $6000–$9FFF au démarrage ; les banques 2 et suivantes sont des overlays chargés dans cette même fenêtre de 16 Kio. Placez le code ou les données d’un overlay avec une directive telle que #pragma fixed_bank 2.

Une banque valide correspondant à la valeur mémorisée renvoie zéro ; sinon, cette fonction appelle __fds_load_bank(). La comparaison initiale reste active avec --fds-no-overlay-guard. La banque 255 n’est jamais considérée comme résidente, même si la valeur mémorisée est 255.

La banque 1 est restaurée depuis un fichier PRG de démarrage distinct de 16 384 octets à $6000. Sans manifeste, les fichiers par défaut ont l’ID 0 pour la banque 1, l’ID 1 pour le code commun et l’ID 2 pour CHR. Un manifeste personnalisé doit scinder le PRG de démarrage en fichiers de 16 384 octets à $6000 et $A000. Pour les banques à partir de 2, l’identifiant est --fds-overlay-start-id (32 par défaut) + numéro de banque − 2.

Charger une autre banque directement depuis du code dans la fenêtre $6000–$9FFF peut écraser la fonction en cours ou son adresse de retour. Cet exemple place l’appelant et le code d’affichage dans #pragma fixed_bank 0. Pour appeler une fonction d’une autre banque puis revenir, utilisez __fds_overlay_farcall() ou un appel de fonction typé ordinaire.

Les appels BIOS sont synchrones ; cette API ne fait pas avancer la boucle de jeu une fois par image pendant un chargement. Utilisez-la depuis le code de contrôle ordinaire de la banque commune, et non depuis un gestionnaire d’interruption. La continuité de l’affichage et de l’audio ainsi que la coexistence avec le véritable BIOS doivent être vérifiées séparément.

Ces captures utilisent un programme de test original de la convention d’appel LoadFiles pour vérifier le code CPU compilé, les transferts mémoire et chaque pixel affiché. Elles ne vérifient ni le véritable BIOS, ni la durée des transferts disque, ni le CRC, ni le démarrage sur matériel réel. Le modèle de contrôleur FDS de KUROSAKI est partiel ; une exécution ordinaire sans ce programme de test ne prouve pas les mêmes résultats de transfert.

La première commande de compilation ci-dessous construit l’exemple téléchargeable. Le vérificateur Python compile les cinq leçons avec et sans optimisation, puis les vérifie dans KUROSAKI. Il crée et supprime un programme de test temporaire à partir de scripts/fds_abi_fixture.py ; ces vérifications ne nécessitent aucun BIOS externe. Ce programme de test n’est pas un BIOS pour les jeux ordinaires.

Exemple d’utilisation

#pragma fixed_bank 0
#include "fc_fds_scene.h"
#pragma fixed_bank 2
__prg_rom u8 bank_payload[4]={11,22,33,44};
#pragma fixed_bank 0
void main(void) {
    __irq_disable();
    fds_result[0]=__fds_load_bank(2);
    fds_result[1]=__fds_current_bank();
    fds_result[2]=__fds_require_bank(2);
    fds_result[3]=bank_payload[0];fds_result[4]=bank_payload[3];
    fds_result[5]=nes_fds_load_bank(1);
    fds_result[6]=__fds_current_bank();
    fds_result[7]=__fds_require_bank(1);
    fds_result[8]=__fds_load_bank(0);
    fds_result[9]=__fds_load_bank(255);
    fds_result[15]=165;
    m_init();m_text(2,2,"FDS DATA WINDOW");m_wait();
    m_text(2,5,"LOAD BANK 2 STATUS");fds_number(25,5,fds_result[0]);m_wait();
    m_text(2,7,"FIRST / LAST BYTE");fds_number(21,7,fds_result[3]);fds_number(25,7,fds_result[4]);m_wait();
    m_text(2,9,"REQUIRE SAME BANK");fds_number(25,9,fds_result[2]);m_wait();
    m_text(2,11,"RESTORE BANK 1");fds_number(25,11,fds_result[5]);m_wait();
    m_text(2,13,"RESIDENT BANK");fds_number(25,13,fds_result[6]);m_wait();
    m_text(2,16,"INVALID BANKS 0 / 255");m_wait();
    fds_number(2,18,fds_result[8]);fds_number(8,18,fds_result[9]);m_wait();
    while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Avec le programme de test original de l’ABI LoadFiles, LOAD BANK 2 STATUS, REQUIRE SAME BANK et RESTORE BANK 1 valent tous 000. FIRST / LAST BYTE affiche 011 et 044, issus des quatre octets transférés ; RESIDENT BANK vaut 001 après restauration. Les banques invalides 0 et 255 renvoient chacune 255. Demander la même banque ne provoque aucun chargement supplémentaire : les requêtes de fichiers vérifiées sont 32, puis 0.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\fds_bank_load.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fds_bank_load.fds --mapper=fds --fds-layout=fds32 --fds-no-license-bypass --fds-overlay-trim --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
python .\kitaq-docs\tools\check_fds_load_examples.py

Return zero when the software residency record matches, otherwise call __fds_load_bank.

EmitHelperStart("__fds_require_bank");
            string fdsRequireLoad = NewGeneratedLabel("fds_require_load");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("CMP", Imm(0xFF));
            EmitAsm("BEQ", Rel(fdsRequireLoad));
            EmitAsm("CMP", Mem(_runtimeFdsResidentBankAddress));
            EmitAsm("BNE", Rel(fdsRequireLoad));
            EmitAsm("LDA", Imm(0));
            EmitAsm("RTS");
            _assembly.Add(Expr.Make(Tag.Label, fdsRequireLoad));
            EmitAsm("JSR", Abs("__fds_load_bank"));
            EmitAsm("RTS");

            // Compare the requested bank with the software residency record and return zero or one.

Écrit les trois arguments bruts dans $4080, $4084 puis $408A.

Syntaxe

void __fds_env_set(u8 speed, u8 gain, u8 mode);

Paramètres

speed

Malgré le nom du paramètre, il s’agit de la valeur brute de $4080 : bit 7 volume direct, bit 6 enveloppe croissante.

gain

Valeur brute d’enveloppe de modulation écrite dans $4084.

mode

Vitesse maîtresse d’enveloppe écrite dans $408A.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Construisez une image .fds avec --mapper=fds. Cette leçon utilise le son sans entrées/sorties disque. L’enregistrement passe par le démarrage direct en RAM et le modèle audio de KUROSAKI. Le micrologiciel de test vide n’implémente aucune routine BIOS et n’est pas distribué. Le démarrage disque normal et le matériel réel nécessitent un environnement d’amorçage adapté.

Exemple d’utilisation

// Mapper 20 sound lesson: original 64-step triangle and two sustained pitches.
#include "fc_sound_example.h"
#include "fds_sound.h"
#include "nes_game.h"
__location(0x4087) u8 mod_control;
__location(0x4085) u8 mod_counter;
u8 triangle[64]; u8 modulation[32];
void main(void) {
    u8 i;
    sound_begin("FDS WAVE AND VOLUME");
    for(i=0;i<32;i++) { triangle[i]=(u8)(i*2); triangle[63-i]=(u8)(i*2); modulation[i]=0; }
    __fds_sound_enable();
    // Halt/reset modulation before writing the 32 values (each writes two slots).
    mod_control=0x80; mod_counter=0;
    __fds_mod_load(modulation);
    __fds_wave_load(triangle);
    sound_result[0]=*((u8*)0x4040); sound_result[1]=*((u8*)0x405F);
    __fds_freq_set(1031);
    __fds_volume_set(24);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    // This macro forwards the same 64-byte load. Use raw envelope registers.
    nes_fds_wave_load(triangle);
    __fds_env_set(0x98,0x80,0);
    __fds_freq_set(1545);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    sound_end();
}

Résultat attendu

Un triangle original de 64 pas joue à environ 440 Hz, s’interrompt, joue à environ 660 Hz puis s’arrête. La seconde note utilise nes_fds_wave_load et des réglages bruts d’enveloppe. Cela vérifie le modèle audio et le démarrage direct, pas l’amorçage disque par BIOS.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_fds.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-fds.fds --mapper=fds --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Write the three raw arguments to 4080, 4084 and 408A in that order.
The legacy parameter names do not describe three independently packed envelope fields.

case "__fds_env_set":
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1}, "__fds_env_set");
                // File helpers use byte identifiers and word memory addresses/lengths.

EmitHelperStart("__fds_env_set");
            EmitAsm("LDA", Mem(CallArgBase)); EmitAsm("STA", Mem(0x4080));
            EmitAsm("LDA", Mem(CallArgBase + 1)); EmitAsm("STA", Mem(0x4084));
            EmitAsm("LDA", Mem(CallArgBase + 2)); EmitAsm("STA", Mem(0x408A));
            EmitAsm("RTS");

Écrit la fréquence de 12 bits dans $4082/$4083 et efface les bits de contrôle supérieurs de $4083.

Syntaxe

void __fds_freq_set(u16 freq);

Paramètres

freq

Valeur de registre de fréquence FDS de 0 à 4095. Les bits de contrôle supérieurs sont effacés.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Construisez une image .fds avec --mapper=fds. Cette leçon utilise le son sans entrées/sorties disque. L’enregistrement passe par le démarrage direct en RAM et le modèle audio de KUROSAKI. Le micrologiciel de test vide n’implémente aucune routine BIOS et n’est pas distribué. Le démarrage disque normal et le matériel réel nécessitent un environnement d’amorçage adapté.

Exemple d’utilisation

// Mapper 20 sound lesson: original 64-step triangle and two sustained pitches.
#include "fc_sound_example.h"
#include "fds_sound.h"
#include "nes_game.h"
__location(0x4087) u8 mod_control;
__location(0x4085) u8 mod_counter;
u8 triangle[64]; u8 modulation[32];
void main(void) {
    u8 i;
    sound_begin("FDS WAVE AND VOLUME");
    for(i=0;i<32;i++) { triangle[i]=(u8)(i*2); triangle[63-i]=(u8)(i*2); modulation[i]=0; }
    __fds_sound_enable();
    // Halt/reset modulation before writing the 32 values (each writes two slots).
    mod_control=0x80; mod_counter=0;
    __fds_mod_load(modulation);
    __fds_wave_load(triangle);
    sound_result[0]=*((u8*)0x4040); sound_result[1]=*((u8*)0x405F);
    __fds_freq_set(1031);
    __fds_volume_set(24);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    // This macro forwards the same 64-byte load. Use raw envelope registers.
    nes_fds_wave_load(triangle);
    __fds_env_set(0x98,0x80,0);
    __fds_freq_set(1545);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    sound_end();
}

Résultat attendu

Un triangle original de 64 pas joue à environ 440 Hz, s’interrompt, joue à environ 660 Hz puis s’arrête. La seconde note utilise nes_fds_wave_load et des réglages bruts d’enveloppe. Cela vérifie le modèle audio et le démarrage direct, pas l’amorçage disque par BIOS.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_fds.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-fds.fds --mapper=fds --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Write a 12-bit frequency to 4082/4083; upper control bits in 4083 are cleared.

case "__fds_freq_set":
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2}, "__fds_freq_set");
                // Clamp the direct volume field to six bits and set the fixed-volume control bit.

EmitHelperStart("__fds_freq_set");
            EmitAsm("LDA", Mem(CallArgBase)); EmitAsm("STA", Mem(0x4082));
            EmitAsm("LDA", Mem(CallArgBase + 1)); EmitAsm("AND", Imm(0x0F)); EmitAsm("STA", Mem(0x4083));
            EmitAsm("RTS");

Envoie 32 octets dans l’ordre au port d’écriture de table de modulation $4088.

Syntaxe

void __fds_mod_load(const u8* mod32);

Paramètres

mod32

Trente-deux octets pour la table de modulation FDS, chacun un code de contrôle de 0 à 7. Arrêtez la modulation avant le chargement.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Construisez une image .fds avec --mapper=fds. Cette leçon utilise le son sans entrées/sorties disque. L’enregistrement passe par le démarrage direct en RAM et le modèle audio de KUROSAKI. Le micrologiciel de test vide n’implémente aucune routine BIOS et n’est pas distribué. Le démarrage disque normal et le matériel réel nécessitent un environnement d’amorçage adapté.

Exemple d’utilisation

// Mapper 20 sound lesson: original 64-step triangle and two sustained pitches.
#include "fc_sound_example.h"
#include "fds_sound.h"
#include "nes_game.h"
__location(0x4087) u8 mod_control;
__location(0x4085) u8 mod_counter;
u8 triangle[64]; u8 modulation[32];
void main(void) {
    u8 i;
    sound_begin("FDS WAVE AND VOLUME");
    for(i=0;i<32;i++) { triangle[i]=(u8)(i*2); triangle[63-i]=(u8)(i*2); modulation[i]=0; }
    __fds_sound_enable();
    // Halt/reset modulation before writing the 32 values (each writes two slots).
    mod_control=0x80; mod_counter=0;
    __fds_mod_load(modulation);
    __fds_wave_load(triangle);
    sound_result[0]=*((u8*)0x4040); sound_result[1]=*((u8*)0x405F);
    __fds_freq_set(1031);
    __fds_volume_set(24);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    // This macro forwards the same 64-byte load. Use raw envelope registers.
    nes_fds_wave_load(triangle);
    __fds_env_set(0x98,0x80,0);
    __fds_freq_set(1545);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    sound_end();
}

Résultat attendu

Un triangle original de 64 pas joue à environ 440 Hz, s’interrompt, joue à environ 660 Hz puis s’arrête. La seconde note utilise nes_fds_wave_load et des réglages bruts d’enveloppe. Cela vérifie le modèle audio et le démarrage direct, pas l’amorçage disque par BIOS.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_fds.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-fds.fds --mapper=fds --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Stream 32 readable bytes to 4088; the caller prepares modulation state and write conditions.

case "__fds_mod_load":
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2}, "__fds_mod_load");

EmitHelperStart("__fds_mod_load");
            EmitAsm("LDY", Imm(0));
            string modLoop = NewGeneratedLabel("fds_mod_loop");
            _assembly.Add(Expr.Make(Tag.Label, modLoop));
            EmitAsm("LDA", IndY(CallArgBase));
            EmitAsm("STA", Mem(0x4088));
            EmitAsm("INY"); EmitAsm("CPY", Imm(32)); EmitAsm("BNE", Rel(modLoop));
            EmitAsm("RTS");

Écrit 0x83 dans la commande disque/son $4023 et met à zéro le contrôle d’onde $4089 et la vitesse $408A.

Syntaxe

void __fds_sound_enable(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Construisez une image .fds avec --mapper=fds. Cette leçon utilise le son sans entrées/sorties disque. L’enregistrement passe par le démarrage direct en RAM et le modèle audio de KUROSAKI. Le micrologiciel de test vide n’implémente aucune routine BIOS et n’est pas distribué. Le démarrage disque normal et le matériel réel nécessitent un environnement d’amorçage adapté.

Exemple d’utilisation

// Mapper 20 sound lesson: original 64-step triangle and two sustained pitches.
#include "fc_sound_example.h"
#include "fds_sound.h"
#include "nes_game.h"
__location(0x4087) u8 mod_control;
__location(0x4085) u8 mod_counter;
u8 triangle[64]; u8 modulation[32];
void main(void) {
    u8 i;
    sound_begin("FDS WAVE AND VOLUME");
    for(i=0;i<32;i++) { triangle[i]=(u8)(i*2); triangle[63-i]=(u8)(i*2); modulation[i]=0; }
    __fds_sound_enable();
    // Halt/reset modulation before writing the 32 values (each writes two slots).
    mod_control=0x80; mod_counter=0;
    __fds_mod_load(modulation);
    __fds_wave_load(triangle);
    sound_result[0]=*((u8*)0x4040); sound_result[1]=*((u8*)0x405F);
    __fds_freq_set(1031);
    __fds_volume_set(24);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    // This macro forwards the same 64-byte load. Use raw envelope registers.
    nes_fds_wave_load(triangle);
    __fds_env_set(0x98,0x80,0);
    __fds_freq_set(1545);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    sound_end();
}

Résultat attendu

Un triangle original de 64 pas joue à environ 440 Hz, s’interrompt, joue à environ 660 Hz puis s’arrête. La seconde note utilise nes_fds_wave_load et des réglages bruts d’enveloppe. Cela vérifie le modèle audio et le démarrage direct, pas l’amorçage disque par BIOS.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_fds.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-fds.fds --mapper=fds --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Write 83 to 4023 and zero to 4089/408A to initialize disk/sound register gates.

case "__fds_sound_enable":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Imm(0x83));
                    EmitAsm("STA", Mem(0x4023));
                    EmitAsm("LDA", Imm(0x00));
                    EmitAsm("STA", Mem(0x4089));
                    EmitAsm("LDA", Imm(0x00));
                    EmitAsm("STA", Mem(0x408A));
                    return true;
                // Wave, modulation and frequency operations pass word arguments to their dedicated helpers.

Écrit les six bits bas du volume avec 0x80 dans $4080 pour le contrôle direct du volume.

Syntaxe

void __fds_volume_set(u8 vol);

Paramètres

vol

Volume direct FDS de 0 à 63 ; le masquage sur six bits ramène 64 à zéro.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Construisez une image .fds avec --mapper=fds. Cette leçon utilise le son sans entrées/sorties disque. L’enregistrement passe par le démarrage direct en RAM et le modèle audio de KUROSAKI. Le micrologiciel de test vide n’implémente aucune routine BIOS et n’est pas distribué. Le démarrage disque normal et le matériel réel nécessitent un environnement d’amorçage adapté.

Exemple d’utilisation

// Mapper 20 sound lesson: original 64-step triangle and two sustained pitches.
#include "fc_sound_example.h"
#include "fds_sound.h"
#include "nes_game.h"
__location(0x4087) u8 mod_control;
__location(0x4085) u8 mod_counter;
u8 triangle[64]; u8 modulation[32];
void main(void) {
    u8 i;
    sound_begin("FDS WAVE AND VOLUME");
    for(i=0;i<32;i++) { triangle[i]=(u8)(i*2); triangle[63-i]=(u8)(i*2); modulation[i]=0; }
    __fds_sound_enable();
    // Halt/reset modulation before writing the 32 values (each writes two slots).
    mod_control=0x80; mod_counter=0;
    __fds_mod_load(modulation);
    __fds_wave_load(triangle);
    sound_result[0]=*((u8*)0x4040); sound_result[1]=*((u8*)0x405F);
    __fds_freq_set(1031);
    __fds_volume_set(24);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    // This macro forwards the same 64-byte load. Use raw envelope registers.
    nes_fds_wave_load(triangle);
    __fds_env_set(0x98,0x80,0);
    __fds_freq_set(1545);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    sound_end();
}

Résultat attendu

Un triangle original de 64 pas joue à environ 440 Hz, s’interrompt, joue à environ 660 Hz puis s’arrête. La seconde note utilise nes_fds_wave_load et des réglages bruts d’enveloppe. Cela vérifie le modèle audio et le démarrage direct, pas l’amorçage disque par BIOS.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_fds.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-fds.fds --mapper=fds --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Write (volume & 3F) | 80 to 4080 for direct volume control; masking wraps, rather than clamps.

case "__fds_volume_set":
                    if (!Need(1)) return true;
                    Load1(args[0]);
                    EmitAsm("AND", Imm(0x3F));
                    EmitAsm("ORA", Imm(0x80));
                    EmitAsm("STA", Mem(0x4080));
                    return true;

Active l’écriture d’onde, copie 64 octets dans $4040..$407F, puis remet $4089 à zéro.

Syntaxe

void __fds_wave_load(const u8* wave64);

Paramètres

wave64

Soixante-quatre octets d’onde FDS, chacun représentant une amplitude sur six bits de 0 à 63. NULL n’est pas vérifié.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Construisez une image .fds avec --mapper=fds. Cette leçon utilise le son sans entrées/sorties disque. L’enregistrement passe par le démarrage direct en RAM et le modèle audio de KUROSAKI. Le micrologiciel de test vide n’implémente aucune routine BIOS et n’est pas distribué. Le démarrage disque normal et le matériel réel nécessitent un environnement d’amorçage adapté.

Exemple d’utilisation

// Mapper 20 sound lesson: original 64-step triangle and two sustained pitches.
#include "fc_sound_example.h"
#include "fds_sound.h"
#include "nes_game.h"
__location(0x4087) u8 mod_control;
__location(0x4085) u8 mod_counter;
u8 triangle[64]; u8 modulation[32];
void main(void) {
    u8 i;
    sound_begin("FDS WAVE AND VOLUME");
    for(i=0;i<32;i++) { triangle[i]=(u8)(i*2); triangle[63-i]=(u8)(i*2); modulation[i]=0; }
    __fds_sound_enable();
    // Halt/reset modulation before writing the 32 values (each writes two slots).
    mod_control=0x80; mod_counter=0;
    __fds_mod_load(modulation);
    __fds_wave_load(triangle);
    sound_result[0]=*((u8*)0x4040); sound_result[1]=*((u8*)0x405F);
    __fds_freq_set(1031);
    __fds_volume_set(24);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    // This macro forwards the same 64-byte load. Use raw envelope registers.
    nes_fds_wave_load(triangle);
    __fds_env_set(0x98,0x80,0);
    __fds_freq_set(1545);
    sound_wait(60);
    __fds_volume_set(0); sound_wait(30);
    sound_end();
}

Résultat attendu

Un triangle original de 64 pas joue à environ 440 Hz, s’interrompt, joue à environ 660 Hz puis s’arrête. La seconde note utilise nes_fds_wave_load et des réglages bruts d’enveloppe. Cela vérifie le modèle audio et le démarrage direct, pas l’amorçage disque par BIOS.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_fds.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-fds.fds --mapper=fds --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Copy exactly 64 readable bytes to wave RAM with wave writes enabled, then set 4089 to zero.

case "__fds_wave_load":
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2}, "__fds_wave_load");

EmitHelperStart("__fds_wave_load");
            EmitAsm("LDA", Imm(0x80)); EmitAsm("STA", Mem(0x4089));
            EmitAsm("LDY", Imm(0));
            string waveLoop = NewGeneratedLabel("fds_wave_loop");
            _assembly.Add(Expr.Make(Tag.Label, waveLoop));
            EmitAsm("LDA", IndY(CallArgBase));
            EmitAsm("STA", new AsmOperand(0x4040, AddressMode.AbsoluteY));
            EmitAsm("INY"); EmitAsm("CPY", Imm(64)); EmitAsm("BNE", Rel(waveLoop));
            EmitAsm("LDA", Imm(0x00)); EmitAsm("STA", Mem(0x4089));
            EmitAsm("RTS");

Point d’entrée NMI qui fait avancer les durées BGM et SFX et met à jour l’APU selon le contrôle actuel de chaque canal.

Syntaxe

void __nes_audio_vblank_tick(void);

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Incluez audio_vblank.h et ajoutez audio_vblank.c à la compilation exactement une fois. Le compilateur appelle son point d’entrée une fois depuis le gestionnaire NMI, qu’il soit standard ou personnalisé. Activez la NMI du PPU. La boucle principale n’appelle pas de routine de mise à jour musicale.

Ce pilote à quatre canaux est réglé pour le NTSC : CH1=impulsion 1, CH2=impulsion 2, CH3=triangle et CH4=bruit, avec des indices de 0 à 3. Il ne gère ni le DMC ni les extensions audio. Ne l’utilisez pas en parallèle avec du code écrivant directement dans l’APU, comme les effets de audio.c. Il ne fournit ni table de fréquences PAL ni correction de tempo pour le PAL.

N’appelez pas cette fonction directement depuis l’application. L’édition de liens avec la bibliothèque musicale la raccorde à la NMI par l’intermédiaire du compilateur. Le point d’entrée sauvegarde A/X/Y et n’utilise pas la zone temporaire partagée des expressions. Ce point d’entrée et les tables de fréquences résident en ROM fixe ; aucune banque ROM n’est commutée dans la NMI. Cette préservation concerne uniquement le point d’entrée musical. Un gestionnaire NMI personnalisé reste responsable de la sauvegarde de l’état utilisé par ses autres traitements.

Un enregistrement contient cinq octets : delay, CH1, CH2, CH3, CH4. Une durée de 1 à 255 indique le nombre de ticks NMI pendant lesquels le nouvel état reste actif. Zéro termine la lecture et les quatre autres octets sont ignorés. Les notes de 0 à 71 correspondent à C2–B7 (24=C4). Pour le bruit, les valeurs 0 à 15 sélectionnent une période en mode long, et 16 à 31 le mode court. Sur tous les canaux, 255=NES_AUDIO_HOLD conserve l’état et 254=NES_AUDIO_STOP coupe le son.

Exemple d’utilisation

// The linked audio_vblank.c supplies __nes_audio_vblank_tick().
    // The compiler calls that hook once per NMI. Do not call it in this loop.
    __nmi_wait();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple joue une fois une phrase originale à quatre canaux. La musique continue pendant que le programme principal effectue des calculs entiers durant 90 images sans remplir la file. « PHRASE COMPLETE / SILENT » et « UNDERRUNS 0 / MATH OK » indiquent que la lecture est terminée, qu’aucun manque de données n’a eu lieu et que les calculs ont donné les résultats attendus. Écoutez l’enregistrement pour reconnaître la mélodie et l’accompagnement à impulsions, la basse triangulaire et le bruit. La fin est silencieuse. L’image présente les résultats du contrôle ; l’audio permet d’évaluer le son.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\audio_vblank.c .\kitaq-docs\samples\api-examples\fc\audio_vblank.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr -o .\out\audio_vblank.nes --no-cache --no-disasm

NMI hook: invoke exactly once per NMI. With a custom handler or a compiler
without automatic audio-hook linking, call it there. Never call from main
or call it again if the compiler already inserts the hook.
Saves A/X/Y, uses no compiler scratch bytes and reads only RAM/fixed ROM.

void __nes_audio_vblank_tick(void){
    __asm {
        PHA
        TXA
        PHA
        TYA
        PHA
        LDA nav_paused
        BEQ nav_tick_begin
        JMP nav_tick_exit
nav_tick_begin:
        LDA #0
        STA nav_dirty
        LDA nav_refresh
        BEQ nav_tick_music
        LDA #0
        STA nav_refresh
        LDA #15
        STA nav_dirty
// Advance BGM even when an effect temporarily owns its output channel.
nav_tick_music:
        LDA nav_active
        BNE nav_tick_active
        JMP nav_tick_sfx
nav_tick_active:
        LDA nav_delay
        BEQ nav_tick_next
        DEC nav_delay
        BEQ nav_tick_next
        JMP nav_tick_sfx
nav_tick_next:
        LDX nav_tail
        CPX nav_head
        BNE nav_tick_record
        LDA nav_starved
        BNE nav_tick_empty_done
        INC nav_starved
        LDA nav_underruns
        CMP #255
        BEQ nav_tick_empty_done
        INC nav_underruns
nav_tick_empty_done:
        JSR nav_silence_music
        JMP nav_tick_sfx
nav_tick_record:
        LDA #0
        STA nav_starved
        LDA nav_queue,X
        BNE nav_tick_timed
        STA nav_active
        JSR nav_silence_music
        JMP nav_tick_release
nav_tick_timed:
        STA nav_delay
        LDY #0
// Remember the new BGM notes but do not retrigger channels owned by SFX.
nav_tick_copy:
        INX
        LDA nav_queue,X
        CMP #255
        BEQ nav_tick_copy_next
        STA nav_notes,Y
        LDA nav_bits,Y
        AND nav_previous_mask
        BNE nav_tick_copy_next
        LDA nav_bits,Y
        ORA nav_dirty
        STA nav_dirty
nav_tick_copy_next:
        INY
        CPY #4
        BNE nav_tick_copy
nav_tick_release:
        LDA nav_tail
        CLC
        ADC #5
        CMP #40
        BNE nav_tick_publish
        LDA #0
nav_tick_publish:
        STA nav_tail
// The SFX has its own delay; completion releases its mask automatically.
nav_tick_sfx:
        LDA nav_sfx_active
        BEQ nav_tick_select
        LDA nav_sfx_delay
        BEQ nav_sfx_next
        DEC nav_sfx_delay
        BNE nav_tick_select
nav_sfx_next:
        LDX nav_sfx_cursor
        CPX nav_sfx_length
        BCC nav_sfx_record
        LDA #0
        STA nav_sfx_active
        JMP nav_tick_select
nav_sfx_record:
        LDA nav_sfx_queue,X
        STA nav_sfx_delay
        LDY #0
nav_sfx_copy:
        INX
        LDA nav_sfx_queue,X
        CMP #255
        BEQ nav_sfx_copy_next
        STA nav_sfx_notes,Y
        LDA nav_bits,Y
        AND nav_sfx_mask
        ORA nav_dirty
        STA nav_dirty
nav_sfx_copy_next:
        INY
        CPY #4
        BNE nav_sfx_copy
        INX
        STX nav_sfx_cursor
nav_tick_select:
        LDA #0
        STA nav_effective_mask
        LDA nav_sfx_active
        BEQ nav_tick_restore
        LDA nav_sfx_mask
        STA nav_effective_mask
// A changed ownership bit forces the newly selected note onto the APU.
nav_tick_restore:
        LDA nav_effective_mask
        EOR nav_previous_mask
        ORA nav_dirty
        STA nav_dirty
        LDA nav_effective_mask
        STA nav_previous_mask
        LDA nav_dirty
        AND #1
        BNE nav_apply_0
        JMP nav_done_0
nav_apply_0:
        LDA nav_effective_mask
        AND #1
        BEQ nav_bg_0
        LDA nav_sfx_notes+0
        JMP nav_value_0
nav_bg_0:
        LDA nav_notes+0
nav_value_0:
        CMP #254
        BNE nav_note_0
        LDA nav_enabled
        AND #254
        STA nav_enabled
        STA $4015
        JMP nav_done_0
nav_note_0:
        TAY
        LDA nav_enabled
        ORA #1
        STA nav_enabled
        STA $4015
        LDA nav_timbre+0
        STA $4000
        LDA nav_pulse_lo,Y
        STA $4002
        LDA nav_pulse_hi,Y
        STA $4003
nav_done_0:
        LDA nav_dirty
        AND #2
        BNE nav_apply_1
        JMP nav_done_1
nav_apply_1:
        LDA nav_effective_mask
        AND #2
        BEQ nav_bg_1
        LDA nav_sfx_notes+1
        JMP nav_value_1
nav_bg_1:
        LDA nav_notes+1
nav_value_1:
        CMP #254
        BNE nav_note_1
        LDA nav_enabled
        AND #253
        STA nav_enabled
        STA $4015
        JMP nav_done_1
nav_note_1:
        TAY
        LDA nav_enabled
        ORA #2
        STA nav_enabled
        STA $4015
        LDA nav_timbre+1
        STA $4004
        LDA nav_pulse_lo,Y
        STA $4006
        LDA nav_pulse_hi,Y
        STA $4007
nav_done_1:
        LDA nav_dirty
        AND #4
        BNE nav_apply_2
        JMP nav_done_2
nav_apply_2:
        LDA nav_effective_mask
        AND #4
        BEQ nav_bg_2
        LDA nav_sfx_notes+2
        JMP nav_value_2
nav_bg_2:
        LDA nav_notes+2
nav_value_2:
        CMP #254
        BNE nav_note_2
        LDA nav_enabled
        AND #251
        STA nav_enabled
        STA $4015
        JMP nav_done_2
nav_note_2:
        TAY
        LDA nav_enabled
        ORA #4
        STA nav_enabled
        STA $4015
        LDA nav_timbre+2
        STA $4008
        LDA nav_triangle_lo,Y
        STA $400A
        LDA nav_triangle_hi,Y
        STA $400B
nav_done_2:
        LDA nav_dirty
        AND #8
        BNE nav_apply_3
        JMP nav_done_3
nav_apply_3:
        LDA nav_effective_mask
        AND #8
        BEQ nav_bg_3
        LDA nav_sfx_notes+3
        JMP nav_value_3
nav_bg_3:
        LDA nav_notes+3
nav_value_3:
        CMP #254
        BNE nav_note_3
        LDA nav_enabled
        AND #247
        STA nav_enabled
        STA $4015
        JMP nav_done_3
nav_note_3:
        TAY
        LDA nav_enabled
        ORA #8
        STA nav_enabled
        STA $4015
        LDA nav_timbre+3
        STA $400C
        TYA
        AND #16
        BEQ nav_noise_long
        TYA
        AND #15
        ORA #128
        JMP nav_noise_period
nav_noise_long:
        TYA
nav_noise_period:
        STA $400E
        // A one-shot envelope must outlive its slowest 16-step decay.
        // Length index 1 gives 254 half-frame ticks; index 0 cuts it at 10.
        LDA nav_timbre+3
        AND #16
        BNE nav_noise_constant_length
        LDA #8
        JMP nav_noise_trigger
nav_noise_constant_length:
        LDA #0
nav_noise_trigger:
        STA $400F
nav_done_3:
nav_tick_exit:
        PLA
        TAY
        PLA
        TAX
        PLA
        RTS
// Internal subroutine: stop BGM channels without disturbing an active effect.
// End/underrun forgets the BGM notes without cutting an independent SFX.
nav_silence_music:
        LDA #254
        STA nav_notes+0
        STA nav_notes+1
        STA nav_notes+2
        STA nav_notes+3
        LDA nav_previous_mask
        EOR #15
        ORA nav_dirty
        STA nav_dirty
        RTS
    }
}

Écrit l’octet complet d’attributs compactés à 0x23C0 + (y>>2)*8 + (x>>2) dans la table 0. X/Y sont des coordonnées de tuiles désignant une zone d’attributs de 4×4 tuiles. Remplace les quatre champs de palette sur deux bits, sans fusionner uniquement un quadrant choisi.

Syntaxe

void __attr_set(u8 x, u8 y, u8 attr);

Paramètres

x / y

Coordonnées de tuiles, pas de pixels. Gardez x dans 0..31 et y dans 0..29 pour la carte visible de 32×30 tuiles ; chaque tuile couvre 8×8 pixels. Les arguments d’un octet ne sont pas bornés automatiquement et peuvent écrire hors de la zone voulue.

attr

Octet d’attributs compactés : bits 0–1 pour les 2×2 tuiles en haut à gauche, 2–3 en haut à droite, 4–5 en bas à gauche, 6–7 en bas à droite. Chaque champ choisit une palette de 0 à 3. 0x55, 0xAA et 0xFF choisissent la palette 1, 2 ou 3 dans les quatre quadrants.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

for(i=2;i<12;i=(u8)(i+4)) {
__attr_set(i,6,0xFF);__attr_set(i,10,0xFF); // All quadrants select green.
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Write the entire packed attribute byte at 23C0+(y>>2)*8+(x>>2).
Use tile coordinates below 32; this does not merge a single palette quadrant.

case "__attr_set": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1}, funcName);

void EmitHelperAttrSet()
        {
            EmitHelperStart("__attr_set");
            // args: x,y,attr. Attribute address = $23C0 + (y>>2)*8 + (x>>2), nametable 0.
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("LSR"); EmitAsm("LSR"); EmitAsm("ASL"); EmitAsm("ASL"); EmitAsm("ASL");
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(CallArgBase)); EmitAsm("LSR"); EmitAsm("LSR"); EmitAsm("CLC"); EmitAsm("ADC", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(0x2002)); EmitAsm("LDA", Imm(0x23)); EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("CLC"); EmitAsm("ADC", Imm(0xC0)); EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Mem(CallArgBase + 2)); EmitAsm("STA", Mem(0x2007));
            EmitAsm("RTS");
        }

Sélectionne la table logique nt & 3, réinitialise le verrou PPU et écrit un octet complet d’attributs à 0x23C0 + (nt & 3)*0x400 + (y>>2)*8 + (x>>2). Écrase tous les quadrants de palette de cet octet. La sélection suit le mirroring actuel de la cartouche.

Syntaxe

void __attr_set_nt(u8 nt, u8 x, u8 y, u8 attr);

Paramètres

nt

Sélecteur de table logique. Seuls les deux bits faibles sont utilisés (nt & 3) : 4 choisit la table 0 et 7 la table 3. N’alloue pas de mémoire indépendante et ne change pas le mirroring du mapper.

x / y

Coordonnées de tuiles, pas de pixels. Gardez x dans 0..31 et y dans 0..29 pour la carte visible de 32×30 tuiles ; chaque tuile couvre 8×8 pixels. Les arguments d’un octet ne sont pas bornés automatiquement et peuvent écrire hors de la zone voulue.

attr

Octet d’attributs compactés : bits 0–1 pour les 2×2 tuiles en haut à gauche, 2–3 en haut à droite, 4–5 en bas à gauche, 6–7 en bas à droite. Chaque champ choisit une palette de 0 à 3. 0x55, 0xAA et 0xFF choisissent la palette 1, 2 ou 3 dans les quatre quadrants.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

for(i=18;i<28;i=(u8)(i+4)) {
__attr_set_nt(4,i,6,0x55);__attr_set_nt(4,i,10,0x55); // nt&3=0; red.
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Write a whole packed attribute byte in nametable nt&3; other quadrant fields are overwritten.

case "__attr_set_nt": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1,1}, funcName);
                // Palette loaders receive a word pointer; their fixed data layout is handled by the runtime helper.

void EmitHelperAttrSetNt()
        {
            EmitHelperStart("__attr_set_nt");
            // args: nt,x,y,attr. Attribute address = $23C0 + nt*$400 + (y>>2)*8 + (x>>2).
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("AND", Imm(3));
            EmitAsm("ASL");
            EmitAsm("ASL");
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(0x23));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("LSR"); EmitAsm("LSR"); EmitAsm("ASL"); EmitAsm("ASL"); EmitAsm("ASL");
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(CallArgBase + 1)); EmitAsm("LSR"); EmitAsm("LSR"); EmitAsm("CLC"); EmitAsm("ADC", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(0x2002)); EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("CLC"); EmitAsm("ADC", Imm(0xC0)); EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Mem(CallArgBase + 3)); EmitAsm("STA", Mem(0x2007));
            EmitAsm("RTS");
        }

Obtient le numéro de banque ROM logique attribué à un objet de données ou à une fonction nommée. Résout une information de placement, sans consulter la banque active ni déréférencer un pointeur.

Syntaxe

u8 bank = __bankof(symbol);

Paramètres

symbol

Nom d’un objet ROM ou d’une fonction dont le placement est connu du compilateur ou de l’éditeur de liens. Une variable pointeur ne désigne pas ici l’objet pointé ; une expression d’exécution n’est pas un nom de symbole.

Valeur renvoyée

Un numéro de banque u8. Zéro peut désigner la ROM commune, sans être un sélecteur valide sur toutes les cibles.

Exemple d’utilisation

bank_expect(__bankof(payload)==3,3);
bank_expect(__bankof(callback)==3,4);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple vérifie que payload et callback sont tous deux placés en banque 3. Cela valide les métadonnées de placement ; les lectures et contrôles du rappel vérifient séparément le comportement à l’exécution.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

PRG bank
Resolve a symbol or function placement to its byte bank number at compilation time.

if (expr.MatchAny(Tag.Call, out funcExpr, out args) &&
                funcExpr != null &&
                funcExpr.Match(Tag.Name, out name) &&
                string.Equals(name, "__bankof", StringComparison.Ordinal) &&
                args != null &&
                args.Length == 1 &&
                args[0] != null &&
                args[0].Match(Tag.Name, out string bankedSymbol))
            {
                // Resolve __bankof from placement metadata and keep the byte-sized bank value.
                value = ResolveSymbolBank(bankedSymbol) & 0xFF;
                return true;
            }

Sélectionne une banque PRG logique avec la routine du compilateur propre au mapper et actualise son état interne. Le changement persiste, sans modifier le registre distinct de la bibliothèque bank.

Syntaxe

void __bankswitch(u8 bank);

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

Valeur renvoyée

Aucune (void).

Conditions et limites

Un changement persistant de banque ne doit pas rendre inaccessibles le code exécuté ou son adresse de retour. Placez cet appel, bank_switch elle-même si elle est utilisée, et le code qui suit dans la banque commune ou fixe 0, comme dans l’exemple.

L’état de la bibliothèque commence à zéro et ne détecte pas le mappage initial de la cartouche. Initialisez-le avec bank_switch. Les intrinsèques et écritures directes dans le mapper n’actualisent pas cet état distinct ; bank_get_current ne vérifie donc pas le mappage matériel réel.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

__bankswitch(1);
bank_expect(home1[0]==0xA1,19);
bank_expect(bank_get_current()==2,20); // Intrinsics bypass the library record.
__bankswitch(2);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

bank_switch(2) enregistre et sélectionne d’abord la banque 2. Une commutation directe sélectionne ensuite la banque 1 et lit A1 dans home1, tandis que bank_get_current indique toujours 2 ; après restauration, home2 donne à nouveau B2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Select the mapper-specific PRG bank; the common bank and legal bank range depend on the target board.

case "__prg_bank_set":
                case "__bankswitch":
                    if (!Need(1)) return true;
                    if (Program.NesMapperProfile.IsSurom512 && TryEvaluateConstant(args[0], out int constantBank) && (constantBank < 1 || constantBank > 30))
                    {
                        Program.Error("error KQFC2603 KQFC-SUROM-BANK-RANGE: {0} constant bank {1} is outside 1..30; common bank 0 is not a switch target.", funcName, constantBank);
                        return true;
                    }
                    _mapperWritingFunctions.Add(_currentFunctionName);
                    Load1(args[0]); EmitAsm("JSR", Abs("__kq_prg_set_bank_a")); return true;

Efface le drapeau choisi à 0 sans effacer le reste de l’octet. Utilisez-le pour retirer une condition enregistrée, par exemple un état temporaire. Effacer de nouveau le même bit le laisse à 0.

Syntaxe

void __bit_clear(u8* base, u16 bit);

Paramètres

base

Pointeur vers le premier octet du tableau de drapeaux en mémoire accessible au CPU. Cet appel n’alloue ni n’initialise le tableau. Utilisez de la RAM accessible en écriture pour mettre, effacer ou inverser les bits ; le test ne fait que lire.

bit

Indice de bit u16 à partir de zéro (0–65535), et non décalage d’octet ou masque. L’indice 0 choisit le masque 0x01 dans l’octet 0 ; 7 choisit 0x80 dans l’octet 0 ; 8 choisit 0x01 dans l’octet 1. En général, le décalage est index / 8 et le masque 1 << (index % 8). Pour un tableau de N octets, exigez index < 8*N et une plage d’adresses CPU valide.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’appelant doit fournir assez de stockage. Il n’y a ni argument de longueur, ni découpage aux limites, ni changement de banque, ni transfert graphique automatique. Un grand numéro de bit peut viser un octet bien au-delà du tableau. Gardez le mappage mémoire stable ; n’utilisez pas ces fonctions de drapeaux RAM comme raccourci pour des registres matériels dont les accès ont des effets de bord.

Mise à 1, effacement et inversion lisent un octet, modifient le bit choisi puis réécrivent l’octet. Cette séquence n’est pas atomique. Coordonnez les écritures de la boucle principale et des gestionnaires d’interruption pour ne pas perdre une modification intermédiaire d’un autre bit du même octet.

Le code FC peut intégrer un indice constant ou appeler une fonction auxiliaire générée. Les deux formes utilisent la même numérotation des bits et le même masque de résultat. Ces fonctions partagent les arguments et l’espace temporaire ; n’y réentrez pas depuis NMI/IRQ pendant un autre appel auxiliaire.

Exemple d’utilisation

__bit_clear(bit_flags,2);
bit_clear_value=bit_flags[0]; // A6 & FB = A2, decimal 162.
__bit_clear(bit_flags,2);     // Clearing it twice leaves it clear.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet arrive ici avec l’octet 0 à 0xA6. Effacer le bit 2 donne 0xA2 (binaire 10100010, décimal 162) ; CLEAR BIT2 doit afficher 162. Un nouvel effacement du bit 2 ne change rien. Les autres drapeaux sont préservés dans les deux appels.

Valeurs FC attendues en décimal : TEST OFF 000, TEST ON 128, SET BIT1 166, CLEAR BIT2 162, TOGGLE BIT7 034, RESTORE 162, NEXT BYTE 130, FAILED 000. NEXT BYTE vient de l’activation de l’indice 9 dans le second octet, de 0x80 à 0x82, sans modifier l’octet 0. La capture FC utilise du texte bleu sur noir.

Le programme vérifie chaque transition affichée et indique le nombre d’échecs. Mettre, effacer et inverser ne renvoient rien ; les lignes affichent l’octet RAM obtenu. Des tests distincts sur émulateur comparent les 520 octets de tampons protégés dans 136 cas par plateforme : indices constants et calculés franchissant les limites d’octet et de 256 octets, et les huit masques non nuls possibles. Ce sont des vérifications d’état RAM, pas une démonstration de dessin. Le matériel physique et les écritures concurrentes par interruption n’ont pas été testés.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\bit_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\bit_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Clear the indexed bit in caller storage; no bounds check or interrupt exclusion is inserted.

case "__bit_clear":
                    if (TryEmitBitIntrinsicInline(funcName, args, ctx)) return true;
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,2}, "__bit_clear");

bool TryEmitBitIntrinsicInline(string funcName, Expr[] args, FunctionContext ctx)
        {
            args = args ?? Array.Empty<Expr>();
            if (args.Length != 2) return false;
            if (!TryEvaluateConstant(args[1], out int bit) || bit < 0) return false;
            // Split the bit number into a byte displacement and an in-byte mask.
            int byteOffset = bit >> 3;
            if (byteOffset > 255) return false;
            int mask = 1 << (bit & 7);
            int[] ptr = AcquireTemps(2);
            try
            {
                EmitLoadValue(args[0], ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitAsm("LDY", Imm(byteOffset));
                EmitAsm("LDA", IndY(ptr[0]));
                switch (funcName)
                {
                    case "__bit_test":
                        EmitAsm("AND", Imm(mask));
                        break;
                    case "__bit_set":
                        EmitAsm("ORA", Imm(mask));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    case "__bit_clear":
                        EmitAsm("AND", Imm((~mask) & 0xFF));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    case "__bit_toggle":
                        EmitAsm("EOR", Imm(mask));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    default:
                        return false;
                }
            }
            finally { ReleaseTemps(ptr); }
            return true;
        }

void EmitBitHelper(string name, string op)
        {
            EmitHelperStart(name);
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("AND", Imm(7));
            EmitAsm("TAX");
            string maskDone = NewGeneratedLabel("bit_mask_done");
            string maskLoop = NewGeneratedLabel("bit_mask_loop");
            EmitAsm("BEQ", Rel(maskDone));
            _assembly.Add(Expr.Make(Tag.Label, maskLoop));
            EmitAsm("ASL", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(maskLoop));
            _assembly.Add(Expr.Make(Tag.Label, maskDone));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            for (int i = 0; i < 3; i++) { EmitAsm("LSR", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("ROR", Mem(_runtimeIntrinsicTmp1Address)); }
            // Fold the high displacement into the pointer; indirect-Y adds the low byte and its carry.
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDY", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", IndY(CallArgBase));
            switch (op)
            {
                case "test":
                    EmitAsm("AND", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("RTS");
                    break;
                case "set":
                    EmitAsm("ORA", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
                case "clear":
                    EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("EOR", Imm(0xFF));
                    EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
                    EmitAsm("LDA", IndY(CallArgBase));
                    EmitAsm("AND", Mem(_runtimeIntrinsicTmp2Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
                case "toggle":
                    EmitAsm("EOR", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
            }
        }

Met le drapeau choisi à 1 en préservant les sept autres bits du même octet. Vous pouvez ainsi marquer une quête terminée ou un objet ramassé. Remettre à 1 un bit déjà à 1 ne le change pas ; ce n’est pas une inversion.

Syntaxe

void __bit_set(u8* base, u16 bit);

Paramètres

base

Pointeur vers le premier octet du tableau de drapeaux en mémoire accessible au CPU. Cet appel n’alloue ni n’initialise le tableau. Utilisez de la RAM accessible en écriture pour mettre, effacer ou inverser les bits ; le test ne fait que lire.

bit

Indice de bit u16 à partir de zéro (0–65535), et non décalage d’octet ou masque. L’indice 0 choisit le masque 0x01 dans l’octet 0 ; 7 choisit 0x80 dans l’octet 0 ; 8 choisit 0x01 dans l’octet 1. En général, le décalage est index / 8 et le masque 1 << (index % 8). Pour un tableau de N octets, exigez index < 8*N et une plage d’adresses CPU valide.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’appelant doit fournir assez de stockage. Il n’y a ni argument de longueur, ni découpage aux limites, ni changement de banque, ni transfert graphique automatique. Un grand numéro de bit peut viser un octet bien au-delà du tableau. Gardez le mappage mémoire stable ; n’utilisez pas ces fonctions de drapeaux RAM comme raccourci pour des registres matériels dont les accès ont des effets de bord.

Mise à 1, effacement et inversion lisent un octet, modifient le bit choisi puis réécrivent l’octet. Cette séquence n’est pas atomique. Coordonnez les écritures de la boucle principale et des gestionnaires d’interruption pour ne pas perdre une modification intermédiaire d’un autre bit du même octet.

Le code FC peut intégrer un indice constant ou appeler une fonction auxiliaire générée. Les deux formes utilisent la même numérotation des bits et le même masque de résultat. Ces fonctions partagent les arguments et l’espace temporaire ; n’y réentrez pas depuis NMI/IRQ pendant un autre appel auxiliaire.

Exemple d’utilisation

__bit_set(bit_flags,1);
bit_set_value=bit_flags[0]; // A4 | 02 = A6, decimal 166.
__bit_set(bit_flags,1);     // Setting it twice leaves it set.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Mettez à 1 le bit 1 de 0xA4 : 10100100 | 00000010 devient 10100110, soit 0xA6 (166 en décimal). La ligne SET BIT1 doit afficher 166. L’exemple répète l’opération et vérifie que l’octet reste à 0xA6, montrant que des mises à 1 répétées n’inversent pas le drapeau.

Valeurs FC attendues en décimal : TEST OFF 000, TEST ON 128, SET BIT1 166, CLEAR BIT2 162, TOGGLE BIT7 034, RESTORE 162, NEXT BYTE 130, FAILED 000. NEXT BYTE vient de l’activation de l’indice 9 dans le second octet, de 0x80 à 0x82, sans modifier l’octet 0. La capture FC utilise du texte bleu sur noir.

Le programme vérifie chaque transition affichée et indique le nombre d’échecs. Mettre, effacer et inverser ne renvoient rien ; les lignes affichent l’octet RAM obtenu. Des tests distincts sur émulateur comparent les 520 octets de tampons protégés dans 136 cas par plateforme : indices constants et calculés franchissant les limites d’octet et de 256 octets, et les huit masques non nuls possibles. Ce sont des vérifications d’état RAM, pas une démonstration de dessin. Le matériel physique et les écritures concurrentes par interruption n’ont pas été testés.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\bit_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\bit_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Set the indexed bit in caller storage without changing the other seven bits in that byte.

case "__bit_set":
                    if (TryEmitBitIntrinsicInline(funcName, args, ctx)) return true;
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,2}, "__bit_set");

bool TryEmitBitIntrinsicInline(string funcName, Expr[] args, FunctionContext ctx)
        {
            args = args ?? Array.Empty<Expr>();
            if (args.Length != 2) return false;
            if (!TryEvaluateConstant(args[1], out int bit) || bit < 0) return false;
            // Split the bit number into a byte displacement and an in-byte mask.
            int byteOffset = bit >> 3;
            if (byteOffset > 255) return false;
            int mask = 1 << (bit & 7);
            int[] ptr = AcquireTemps(2);
            try
            {
                EmitLoadValue(args[0], ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitAsm("LDY", Imm(byteOffset));
                EmitAsm("LDA", IndY(ptr[0]));
                switch (funcName)
                {
                    case "__bit_test":
                        EmitAsm("AND", Imm(mask));
                        break;
                    case "__bit_set":
                        EmitAsm("ORA", Imm(mask));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    case "__bit_clear":
                        EmitAsm("AND", Imm((~mask) & 0xFF));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    case "__bit_toggle":
                        EmitAsm("EOR", Imm(mask));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    default:
                        return false;
                }
            }
            finally { ReleaseTemps(ptr); }
            return true;
        }

void EmitBitHelper(string name, string op)
        {
            EmitHelperStart(name);
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("AND", Imm(7));
            EmitAsm("TAX");
            string maskDone = NewGeneratedLabel("bit_mask_done");
            string maskLoop = NewGeneratedLabel("bit_mask_loop");
            EmitAsm("BEQ", Rel(maskDone));
            _assembly.Add(Expr.Make(Tag.Label, maskLoop));
            EmitAsm("ASL", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(maskLoop));
            _assembly.Add(Expr.Make(Tag.Label, maskDone));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            for (int i = 0; i < 3; i++) { EmitAsm("LSR", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("ROR", Mem(_runtimeIntrinsicTmp1Address)); }
            // Fold the high displacement into the pointer; indirect-Y adds the low byte and its carry.
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDY", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", IndY(CallArgBase));
            switch (op)
            {
                case "test":
                    EmitAsm("AND", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("RTS");
                    break;
                case "set":
                    EmitAsm("ORA", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
                case "clear":
                    EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("EOR", Imm(0xFF));
                    EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
                    EmitAsm("LDA", IndY(CallArgBase));
                    EmitAsm("AND", Mem(_runtimeIntrinsicTmp2Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
                case "toggle":
                    EmitAsm("EOR", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
            }
        }

Lit un drapeau dans un tableau de bits compactés sans modifier le tableau. Huit drapeaux indépendants peuvent ainsi partager chaque octet de RAM. Le résultat indique si le bit choisi est à zéro ou à un ; sa représentation numérique dépend de la cible.

Syntaxe

u8 __bit_test(u8* base, u16 bit);

Paramètres

base

Pointeur vers le premier octet du tableau de drapeaux en mémoire accessible au CPU. Cet appel n’alloue ni n’initialise le tableau. Utilisez de la RAM accessible en écriture pour mettre, effacer ou inverser les bits ; le test ne fait que lire.

bit

Indice de bit u16 à partir de zéro (0–65535), et non décalage d’octet ou masque. L’indice 0 choisit le masque 0x01 dans l’octet 0 ; 7 choisit 0x80 dans l’octet 0 ; 8 choisit 0x01 dans l’octet 1. En général, le décalage est index / 8 et le masque 1 << (index % 8). Pour un tableau de N octets, exigez index < 8*N et une plage d’adresses CPU valide.

Valeur renvoyée

u8 : 0 si le bit est effacé, sinon son masque : 1, 2, 4, 8, 16, 32, 64 ou 128. Le résultat est base[bit >> 3] & (1 << (bit & 7)). Tester le bit 7 actif renvoie par exemple 128. Utilisez result != 0 pour savoir si le drapeau est actif ; une comparaison à 1 manquerait les autres positions de bit.

Conditions et limites

L’appelant doit fournir assez de stockage. Il n’y a ni argument de longueur, ni découpage aux limites, ni changement de banque, ni transfert graphique automatique. Un grand numéro de bit peut viser un octet bien au-delà du tableau. Gardez le mappage mémoire stable ; n’utilisez pas ces fonctions de drapeaux RAM comme raccourci pour des registres matériels dont les accès ont des effets de bord.

Le code FC peut intégrer un indice constant ou appeler une fonction auxiliaire générée. Les deux formes utilisent la même numérotation des bits et le même masque de résultat. Ces fonctions partagent les arguments et l’espace temporaire ; n’y réentrez pas depuis NMI/IRQ pendant un autre appel auxiliaire.

Exemple d’utilisation

bit_off=__bit_test(bit_flags,1); // Bit 1 of A4 is clear: zero.
bit_on=__bit_test(bit_flags,7);  // Bit 7 is set: GB returns 1; FC returns 128.
bit_is_on=0;
if(bit_on!=0)bit_is_on=1; // The same nonzero test works on both targets.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Commencez avec l’octet 0 à 0xA4 (binaire 10100100). Tester le bit 1 renvoie 0 ; tester le bit 7 renvoie 1 sur GB ou 128 sur FC. L’exemple convertit aussi ce résultat non nul en drapeau commun et vérifie que l’octet initial est inchangé. Regardez TEST OFF et TEST ON dans l’écran ci-dessous.

Valeurs FC attendues en décimal : TEST OFF 000, TEST ON 128, SET BIT1 166, CLEAR BIT2 162, TOGGLE BIT7 034, RESTORE 162, NEXT BYTE 130, FAILED 000. NEXT BYTE vient de l’activation de l’indice 9 dans le second octet, de 0x80 à 0x82, sans modifier l’octet 0. La capture FC utilise du texte bleu sur noir.

Le programme vérifie chaque transition affichée et indique le nombre d’échecs. Mettre, effacer et inverser ne renvoient rien ; les lignes affichent l’octet RAM obtenu. Des tests distincts sur émulateur comparent les 520 octets de tampons protégés dans 136 cas par plateforme : indices constants et calculés franchissant les limites d’octet et de 256 octets, et les huit masques non nuls possibles. Ce sont des vérifications d’état RAM, pas une démonstration de dessin. Le matériel physique et les écritures concurrentes par interruption n’ont pas été testés.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\bit_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\bit_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Return base[bit>>3] & (1<<(bit&7)): zero or the bit mask, not a normalized Boolean.

case "__bit_test":
                    if (TryEmitBitIntrinsicInline(funcName, args, ctx)) return true;
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,2}, "__bit_test");

bool TryEmitBitIntrinsicInline(string funcName, Expr[] args, FunctionContext ctx)
        {
            args = args ?? Array.Empty<Expr>();
            if (args.Length != 2) return false;
            if (!TryEvaluateConstant(args[1], out int bit) || bit < 0) return false;
            // Split the bit number into a byte displacement and an in-byte mask.
            int byteOffset = bit >> 3;
            if (byteOffset > 255) return false;
            int mask = 1 << (bit & 7);
            int[] ptr = AcquireTemps(2);
            try
            {
                EmitLoadValue(args[0], ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitAsm("LDY", Imm(byteOffset));
                EmitAsm("LDA", IndY(ptr[0]));
                switch (funcName)
                {
                    case "__bit_test":
                        EmitAsm("AND", Imm(mask));
                        break;
                    case "__bit_set":
                        EmitAsm("ORA", Imm(mask));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    case "__bit_clear":
                        EmitAsm("AND", Imm((~mask) & 0xFF));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    case "__bit_toggle":
                        EmitAsm("EOR", Imm(mask));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    default:
                        return false;
                }
            }
            finally { ReleaseTemps(ptr); }
            return true;
        }

void EmitBitHelper(string name, string op)
        {
            EmitHelperStart(name);
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("AND", Imm(7));
            EmitAsm("TAX");
            string maskDone = NewGeneratedLabel("bit_mask_done");
            string maskLoop = NewGeneratedLabel("bit_mask_loop");
            EmitAsm("BEQ", Rel(maskDone));
            _assembly.Add(Expr.Make(Tag.Label, maskLoop));
            EmitAsm("ASL", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(maskLoop));
            _assembly.Add(Expr.Make(Tag.Label, maskDone));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            for (int i = 0; i < 3; i++) { EmitAsm("LSR", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("ROR", Mem(_runtimeIntrinsicTmp1Address)); }
            // Fold the high displacement into the pointer; indirect-Y adds the low byte and its carry.
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDY", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", IndY(CallArgBase));
            switch (op)
            {
                case "test":
                    EmitAsm("AND", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("RTS");
                    break;
                case "set":
                    EmitAsm("ORA", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
                case "clear":
                    EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("EOR", Imm(0xFF));
                    EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
                    EmitAsm("LDA", IndY(CallArgBase));
                    EmitAsm("AND", Mem(_runtimeIntrinsicTmp2Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
                case "toggle":
                    EmitAsm("EOR", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
            }
        }

Inverse le drapeau choisi : 0 devient 1 et 1 devient 0. Les autres bits sont préservés. Deux appels sur le même bit rétablissent son état initial, à condition qu’aucune autre écriture de ce bit ne survienne entre les appels.

Syntaxe

void __bit_toggle(u8* base, u16 bit);

Paramètres

base

Pointeur vers le premier octet du tableau de drapeaux en mémoire accessible au CPU. Cet appel n’alloue ni n’initialise le tableau. Utilisez de la RAM accessible en écriture pour mettre, effacer ou inverser les bits ; le test ne fait que lire.

bit

Indice de bit u16 à partir de zéro (0–65535), et non décalage d’octet ou masque. L’indice 0 choisit le masque 0x01 dans l’octet 0 ; 7 choisit 0x80 dans l’octet 0 ; 8 choisit 0x01 dans l’octet 1. En général, le décalage est index / 8 et le masque 1 << (index % 8). Pour un tableau de N octets, exigez index < 8*N et une plage d’adresses CPU valide.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’appelant doit fournir assez de stockage. Il n’y a ni argument de longueur, ni découpage aux limites, ni changement de banque, ni transfert graphique automatique. Un grand numéro de bit peut viser un octet bien au-delà du tableau. Gardez le mappage mémoire stable ; n’utilisez pas ces fonctions de drapeaux RAM comme raccourci pour des registres matériels dont les accès ont des effets de bord.

Mise à 1, effacement et inversion lisent un octet, modifient le bit choisi puis réécrivent l’octet. Cette séquence n’est pas atomique. Coordonnez les écritures de la boucle principale et des gestionnaires d’interruption pour ne pas perdre une modification intermédiaire d’un autre bit du même octet.

Le code FC peut intégrer un indice constant ou appeler une fonction auxiliaire générée. Les deux formes utilisent la même numérotation des bits et le même masque de résultat. Ces fonctions partagent les arguments et l’espace temporaire ; n’y réentrez pas depuis NMI/IRQ pendant un autre appel auxiliaire.

Exemple d’utilisation

__bit_toggle(bit_flags,7);
bit_toggle_value=bit_flags[0]; // A2 ^ 80 = 22, decimal 34.
__bit_toggle(bit_flags,7);
bit_restore_value=bit_flags[0]; // Two toggles restore A2.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet commence cette étape à 0xA2. Inverser le bit 7 donne 0x22 (34 en décimal), donc TOGGLE BIT7 affiche 034. L’inverser encore restaure 0xA2 et RESTORE affiche 162. Ces observations montrent les deux sens de l’inversion tout en préservant les autres bits.

Valeurs FC attendues en décimal : TEST OFF 000, TEST ON 128, SET BIT1 166, CLEAR BIT2 162, TOGGLE BIT7 034, RESTORE 162, NEXT BYTE 130, FAILED 000. NEXT BYTE vient de l’activation de l’indice 9 dans le second octet, de 0x80 à 0x82, sans modifier l’octet 0. La capture FC utilise du texte bleu sur noir.

Le programme vérifie chaque transition affichée et indique le nombre d’échecs. Mettre, effacer et inverser ne renvoient rien ; les lignes affichent l’octet RAM obtenu. Des tests distincts sur émulateur comparent les 520 octets de tampons protégés dans 136 cas par plateforme : indices constants et calculés franchissant les limites d’octet et de 256 octets, et les huit masques non nuls possibles. Ce sont des vérifications d’état RAM, pas une démonstration de dessin. Le matériel physique et les écritures concurrentes par interruption n’ont pas été testés.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\bit_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\bit_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

XOR the indexed bit in caller storage; coordinate concurrent writers to avoid lost updates.

case "__bit_toggle":
                    if (TryEmitBitIntrinsicInline(funcName, args, ctx)) return true;
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,2}, "__bit_toggle");
                // Arithmetic variants share argument packing here; signed/fixed-point arithmetic is implemented by their named helpers.

bool TryEmitBitIntrinsicInline(string funcName, Expr[] args, FunctionContext ctx)
        {
            args = args ?? Array.Empty<Expr>();
            if (args.Length != 2) return false;
            if (!TryEvaluateConstant(args[1], out int bit) || bit < 0) return false;
            // Split the bit number into a byte displacement and an in-byte mask.
            int byteOffset = bit >> 3;
            if (byteOffset > 255) return false;
            int mask = 1 << (bit & 7);
            int[] ptr = AcquireTemps(2);
            try
            {
                EmitLoadValue(args[0], ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitAsm("LDY", Imm(byteOffset));
                EmitAsm("LDA", IndY(ptr[0]));
                switch (funcName)
                {
                    case "__bit_test":
                        EmitAsm("AND", Imm(mask));
                        break;
                    case "__bit_set":
                        EmitAsm("ORA", Imm(mask));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    case "__bit_clear":
                        EmitAsm("AND", Imm((~mask) & 0xFF));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    case "__bit_toggle":
                        EmitAsm("EOR", Imm(mask));
                        EmitAsm("STA", IndY(ptr[0]));
                        break;
                    default:
                        return false;
                }
            }
            finally { ReleaseTemps(ptr); }
            return true;
        }

void EmitBitHelper(string name, string op)
        {
            EmitHelperStart(name);
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("AND", Imm(7));
            EmitAsm("TAX");
            string maskDone = NewGeneratedLabel("bit_mask_done");
            string maskLoop = NewGeneratedLabel("bit_mask_loop");
            EmitAsm("BEQ", Rel(maskDone));
            _assembly.Add(Expr.Make(Tag.Label, maskLoop));
            EmitAsm("ASL", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(maskLoop));
            _assembly.Add(Expr.Make(Tag.Label, maskDone));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            for (int i = 0; i < 3; i++) { EmitAsm("LSR", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("ROR", Mem(_runtimeIntrinsicTmp1Address)); }
            // Fold the high displacement into the pointer; indirect-Y adds the low byte and its carry.
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDY", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", IndY(CallArgBase));
            switch (op)
            {
                case "test":
                    EmitAsm("AND", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("RTS");
                    break;
                case "set":
                    EmitAsm("ORA", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
                case "clear":
                    EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("EOR", Imm(0xFF));
                    EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
                    EmitAsm("LDA", IndY(CallArgBase));
                    EmitAsm("AND", Mem(_runtimeIntrinsicTmp2Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
                case "toggle":
                    EmitAsm("EOR", Mem(_runtimeIntrinsicTmp0Address));
                    EmitAsm("STA", IndY(CallArgBase));
                    EmitAsm("RTS");
                    break;
            }
        }

Sélectionne une banque CHR. Sur MMC3, sélectionne R0 et modifie la fenêtre de 2 Kio à PPU $0000–$07FF. Sur CNROM, modifie toute la région de 8 Kio à $0000–$1FFF.

Syntaxe

void __chr_bank_set(u8 bank);

Paramètres

bank

Sur CNROM, c’est un numéro de banque CHR de 8 Kio. Sur MMC3, c’est un numéro de banque de 1 Kio sélectionnant une fenêtre de 2 Kio : le bit de poids faible est ignoré, donc 2 et 3 sélectionnent tous deux la paire de banques de 1 Kio 2 et 3. Les banques disponibles dépendent de la capacité de la CHR ROM ; l’API ne contrôle pas les limites.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

Écrire 0 ou 1 dans le registre de sélection MMC3 efface aussi le bit 6 de mode PRG et le bit 7 d’inversion CHR. N’utilisez pas cette opération avec une disposition PRG/CHR qui exige de les maintenir actifs. Une commutation pendant le rendu modifie les lectures de motifs suivantes. L’exemple vérifie avec le rendu désactivé et restaure les banques de police avant d’afficher les résultats.

Ces trois intrinsèques prennent en charge CNROM et MMC3. Les autres cartes sont refusées à la compilation. SUROM utilise aussi le contrôle CHR pour sélectionner la région PRG externe et n’autorise pas ces opérations CHR.

Exemple d’utilisation

__chr_bank_set(2);
    mapper_result[1] = mapper_read(0x03FF);
    mapper_result[2] = mapper_read(0x07FF);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple MMC3 affiche les marqueurs CHR 19/20, 21/22 et 23/24. Les lectures CIRAM donnent A B A B en mirroring vertical et A A B B en horizontal. Les comptes IRQ sont 01→02→03→03 : chacune des trois premières activations explicites autorise une interruption ; le compteur reste fixe après désactivation. Chaque étape attend six images.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_controls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_controls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Exemple d’utilisation

__chr_bank_set(2); chr_result[0]=chr_marker();
    __chr_bank_set0(1); chr_result[1]=chr_marker();
    __chr_bank_set1(3); chr_result[2]=chr_marker();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

La leçon CNROM affiche les marqueurs 33, 25 et 41 après SET 2, SET0 1 et SET1 3. Elle lit des octets marqueurs originaux via le PPU pour montrer que les trois noms commutent toute la région de motifs de 8 Kio.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_chr_cnrom.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_chr_cnrom.nes --mapper=cnrom --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Select a CNROM bank or MMC3 register 0 bank; unsupported mapper profiles produce a compile error.

Sélectionne MMC3 R0 et modifie la fenêtre de 2 Kio à PPU $0000–$07FF. Équivaut à __chr_bank_set. Sur CNROM, modifie toute la région de 8 Kio.

Syntaxe

void __chr_bank_set0(u8 bank);

Paramètres

bank

Sur CNROM, c’est un numéro de banque CHR de 8 Kio. Sur MMC3, c’est un numéro de banque de 1 Kio sélectionnant une fenêtre de 2 Kio : le bit de poids faible est ignoré, donc 2 et 3 sélectionnent tous deux la paire de banques de 1 Kio 2 et 3. Les banques disponibles dépendent de la capacité de la CHR ROM ; l’API ne contrôle pas les limites.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

Écrire 0 ou 1 dans le registre de sélection MMC3 efface aussi le bit 6 de mode PRG et le bit 7 d’inversion CHR. N’utilisez pas cette opération avec une disposition PRG/CHR qui exige de les maintenir actifs. Une commutation pendant le rendu modifie les lectures de motifs suivantes. L’exemple vérifie avec le rendu désactivé et restaure les banques de police avant d’afficher les résultats.

Ces trois intrinsèques prennent en charge CNROM et MMC3. Les autres cartes sont refusées à la compilation. SUROM utilise aussi le contrôle CHR pour sélectionner la région PRG externe et n’autorise pas ces opérations CHR.

Exemple d’utilisation

__chr_bank_set0(4);
    mapper_result[3] = mapper_read(0x03FF);
    mapper_result[4] = mapper_read(0x07FF);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple MMC3 affiche les marqueurs CHR 19/20, 21/22 et 23/24. Les lectures CIRAM donnent A B A B en mirroring vertical et A A B B en horizontal. Les comptes IRQ sont 01→02→03→03 : chacune des trois premières activations explicites autorise une interruption ; le compteur reste fixe après désactivation. Chaque étape attend six images.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_controls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_controls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Exemple d’utilisation

__chr_bank_set(2); chr_result[0]=chr_marker();
    __chr_bank_set0(1); chr_result[1]=chr_marker();
    __chr_bank_set1(3); chr_result[2]=chr_marker();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

La leçon CNROM affiche les marqueurs 33, 25 et 41 après SET 2, SET0 1 et SET1 3. Elle lit des octets marqueurs originaux via le PPU pour montrer que les trois noms commutent toute la région de motifs de 8 Kio.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_chr_cnrom.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_chr_cnrom.nes --mapper=cnrom --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Use the same CNROM/MMC3 register 0 selection as __chr_bank_set.

Sélectionne MMC3 R1 et modifie la fenêtre de 2 Kio à PPU $0800–$0FFF sans toucher R0. CNROM n’a pas de seconde fenêtre indépendante ; toute la région de 8 Kio est modifiée.

Syntaxe

void __chr_bank_set1(u8 bank);

Paramètres

bank

Sur CNROM, c’est un numéro de banque CHR de 8 Kio. Sur MMC3, c’est un numéro de banque de 1 Kio sélectionnant une fenêtre de 2 Kio : le bit de poids faible est ignoré, donc 2 et 3 sélectionnent tous deux la paire de banques de 1 Kio 2 et 3. Les banques disponibles dépendent de la capacité de la CHR ROM ; l’API ne contrôle pas les limites.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

Écrire 0 ou 1 dans le registre de sélection MMC3 efface aussi le bit 6 de mode PRG et le bit 7 d’inversion CHR. N’utilisez pas cette opération avec une disposition PRG/CHR qui exige de les maintenir actifs. Une commutation pendant le rendu modifie les lectures de motifs suivantes. L’exemple vérifie avec le rendu désactivé et restaure les banques de police avant d’afficher les résultats.

Ces trois intrinsèques prennent en charge CNROM et MMC3. Les autres cartes sont refusées à la compilation. SUROM utilise aussi le contrôle CHR pour sélectionner la région PRG externe et n’autorise pas ces opérations CHR.

Exemple d’utilisation

__chr_bank_set1(6);
    mapper_result[5] = mapper_read(0x0BFF);
    mapper_result[6] = mapper_read(0x0FFF);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple MMC3 affiche les marqueurs CHR 19/20, 21/22 et 23/24. Les lectures CIRAM donnent A B A B en mirroring vertical et A A B B en horizontal. Les comptes IRQ sont 01→02→03→03 : chacune des trois premières activations explicites autorise une interruption ; le compteur reste fixe après désactivation. Chaque étape attend six images.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_controls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_controls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Exemple d’utilisation

__chr_bank_set(2); chr_result[0]=chr_marker();
    __chr_bank_set0(1); chr_result[1]=chr_marker();
    __chr_bank_set1(3); chr_result[2]=chr_marker();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

La leçon CNROM affiche les marqueurs 33, 25 et 41 après SET 2, SET0 1 et SET1 3. Elle lit des octets marqueurs originaux via le PPU pour montrer que les trois noms commutent toute la région de motifs de 8 Kio.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_chr_cnrom.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_chr_cnrom.nes --mapper=cnrom --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Select MMC3 register 1, or the same full CNROM bank register; this is mapper-specific banking.

Copie exactement 16 octets de src vers dst, sans argument de longueur. On peut ainsi copier un enregistrement de 16 octets ou une tuile GB/NES placée en mémoire accessible au processeur. Le nombre 16 désigne des octets, pas des bits ; cet appel ne charge pas les graphismes dans le matériel vidéo.

Syntaxe

void __copy16(u8* dst, const u8* src);

Paramètres

dst

Pointeur vers le premier octet accessible en écriture de la destination. Prévoyez une zone contiguë assez grande pour toute l’opération ; aucun tampon n’est alloué automatiquement.

src

Pointeur vers le premier octet lisible de la source. Toute la zone doit rester accessible et inchangée pendant la copie.

Valeur renvoyée

Aucune (void).

Conditions et limites

Utilisez des zones source et destination sans chevauchement. Ces routines copient vers les adresses croissantes et n’offrent pas la sécurité de memmove en cas de recouvrement ; écraser une partie de la source encore non lue peut altérer la suite de la copie.

L’opération se termine avant de rendre la main. Elle ne change pas de banque ROM/RAM et ne limite pas automatiquement la zone aux bornes d’un tampon. Maintenez le mappage stable, utilisez des zones valides et coordonnez l’accès avec les interruptions utilisant les mêmes tampons.

Sur FC, dst est une adresse CPU, pas une adresse PPU. Une copie en RAM CPU ne modifie ni CHR, ni les tables de noms, ni les palettes ; leur chargement nécessite les API PPU/VRAM. Les routines auxiliaires générées partagent les arguments et les temporaires : ne les rappelez pas depuis une NMI/IRQ pendant une opération en cours.

Exemple d’utilisation

memory_reset();
__copy16(memory_destination+1,memory_source+1);
memory_copy_16=memory_check(16,0); // Exactly 16 bytes, not 16 bits.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet exemple utilise __copy16 pour copier 16 octets suivant un motif connu à partir du décalage 1. memory_check compare les tableaux source et destination en entier ; la ligne COPY16 doit afficher 016. Le premier octet sert de garde et les octets suivant le bloc doivent également rester inchangés.

Le programme complet initialise deux tampons de 264 octets avant chaque opération, puis vérifie tous les octets de la source, de la destination et des zones de garde. L’écran attendu affiche COPY WORD 257, FILL WORD 257, COPY BYTE 255, FILL BYTE 255, COPY16 016, COPY32 032, ZERO CALLS 002 et FAILED 000. WORD/BYTE désignent la largeur du compteur, pas la taille des éléments copiés. Ces nombres proviennent des vérifications de l’exemple ; ces fonctions void ne renvoient aucune valeur.

Les captures montrent du texte noir sur blanc sur DMG, bleu sur blanc sur CGB et bleu sur noir sur FC. L’exemple vérifie des opérations en RAM ; le texte en présente les résultats, sans illustrer une primitive de dessin. Des contrôles distincts sur émulateur couvrent 88 cas par plateforme : longueurs constantes ou déterminées à l’exécution de 0, 1, 16, 17, 32, 33, 64, 65 et 255 octets, plus 256 et 257 pour les compteurs sur 16 bits. Aucun test sur matériel réel n’a été effectué.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\memory_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\memory_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Copy exactly 16 bytes forward; both ranges must be valid and suitably non-overlapping.

case "__copy16":
                    if (!Need(2)) return true;
                    EmitFixedMemcpy(args[0], args[1], 16, ctx); return true;

void EmitFixedMemcpy(Expr dstExpr, Expr srcExpr, int len, FunctionContext ctx)
        {
            int[] ptr = AcquireTemps(4);
            try
            {
                EmitLoadValue(dstExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitLoadValue(srcExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[2]));
                EmitAsm("STX", Mem(ptr[3]));
                for (int i = 0; i < len; i++)
                {
                    EmitAsm("LDY", Imm(i));
                    EmitAsm("LDA", IndY(ptr[2]));
                    EmitAsm("STA", IndY(ptr[0]));
                }
            }
            finally { ReleaseTemps(ptr); }
        }

// kitaqfc/kitaqfc/Lowerer.cs:2128
if (expr.MatchAny(Tag.Call, out callFunc, out callArgs))
        {
            string knownCallName;
            if (callFunc != null && callFunc.Match(Tag.Name, out knownCallName) &&
                knownCallName == "__cgb_is_cgb" &&
                callArgs != null && callArgs.Length == 0 &&
                // A resolved target configuration can replace the zero-argument CGB query with a literal.
                Program.TryGetKnownCgbRuntimeValue(out int knownCgbValue))
            {
                return Expr.Make(Tag.Integer, knownCgbValue).WithSource(expr.Source);
            }

            Expr newFunc = LowerExpr(ctx, callFunc, false, prefix);

            // Optimization (post-A3): when we must spill a non-atomic argument into a temp,
            // prefer a u8 temp if the *parameter type* is u8-like.
            // This preserves semantics (implicit truncation to u8) while avoiding needless
            // u16 temporaries created by integer promotions.
            CType[] paramTypes = null;
            string __fname = null;
            if (newFunc.Match(Tag.Name, out __fname))
            {
                paramTypes = ctx.FindFuncParams(__fname);
                if (paramTypes == null)
                {
                    CType fnTypeFromName;
                    if (TryGetCallableFunctionType(ctx.FindTypeOfName(__fname), out fnTypeFromName))
                        paramTypes = fnTypeFromName.ParamTypes;
                }
            }
            else
            {
                CType fnTypeFromExpr;
                if (TryGetCallableFunctionType(InferType(ctx, newFunc), out fnTypeFromExpr))
                    paramTypes = fnTypeFromExpr.ParamTypes;
            }

            Expr[] newArgs = new Expr[callArgs.Length];
            for (int i = 0; i < callArgs.Length; i++)
            {
                Expr a = LowerExpr(ctx, callArgs[i], allowExtract, prefix);

                bool preserveConstantArgIntrinsic = false;
                if (a.MatchAny(Tag.Call, out Expr argFunc, out Expr[] _argCallArgs) &&
                    argFunc.Match(Tag.Name, out string argFuncName))
                {
                    preserveConstantArgIntrinsic = (argFuncName == "__bankof" || argFuncName == "__cgb_is_cgb");
                }
                // Keep evaluable constants and special intrinsic/bank operands visible to code generation instead of spilling them.
                bool preserveCompileTimeConstantArg = ctx.Global.TryEvalConstInt(a, out _);
                bool preserveFarcallBankArg = (__fname == "__farcall" && i == 0);

                if (allowExtract && !preserveFarcallBankArg && !preserveConstantArgIntrinsic && !preserveCompileTimeConstantArg && !IsAtom(a))
                {
                    // If we know the callee's parameter type, use it to choose a smaller temp.
                    // Example: (u8)(row*32) passed to a u8 param should spill as u8, not u16.
                    CType spillAs = null;
                    if (paramTypes != null && i < paramTypes.Length)
                    {
                        CType pt = paramTypes[i];
                        if (IsU8Like(pt)) spillAs = CType.UInt8;
                    }
                    if (spillAs == null) spillAs = InferType(ctx, a);
                    if (!IsAggregateType(spillAs) && SizeOfType(spillAs) <= 2)
                        a = SpillToTemp(ctx, a, spillAs, prefix);
                }
                newArgs[i] = a;
            }

            // Lint: const discard for argument passing
            // Warn when passing a const-qualified pointer (or const array decay) to a non-const pointer parameter.
            // Suppress when the argument has an explicit cast, or inside __unsafe.
            if (!ctx.InUnsafe && paramTypes != null)
            {
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;
                    if (!IsPointerToNonConst(pt)) continue;
                    if (HasTopLevelCast(newArgs[i])) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at != null && (IsPointerToConst(at) || IsArrayOfConst(at)))
                    {
                        string fn = __fname ?? "<call>";
                        WarnConstDiscard(expr, $"argument {i} to '{fn}'");
                        break; // keep it quiet: one warning per call is enough
                    }
                }
            }

            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    FilePosition argPos = newArgs[i].Source;
                    if (string.IsNullOrEmpty(argPos.Filename) || argPos.Filename == "<unknown>")
                        argPos = expr.Source;
                    WarnImplicitNarrowingIfNeeded(ctx, newArgs[i], InferType(ctx, newArgs[i]), paramTypes[i], argPos,
                        "argument " + i + " to '" + fn + "'");
                }
            }

            // Lint: __enum_strict argument passing.
            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at == null) continue;

                    if (HasTopLevelCast(newArgs[i])) continue;

                    if (IsStrictEnum(pt))
                    {
                        if (!IsSameEnum(pt, at))
                        {
                            Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                                "argument {0} to '{1}' expects __enum_strict {2}, got {3}; cast explicitly to silence",
                                i, fn, pt.Show(), at.Show());
                        }
                    }
                    else if (IsPlainInteger(pt) && IsStrictEnum(at))
                    {
                        Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                            "argument {0} to '{1}' passes __enum_strict {2} to integer parameter {3}; cast explicitly to silence",
                            i, fn, at.Show(), pt.Show());
                    }
                }
            }

            if (!ctx.InUnsafe)
                RestrictAliasLint(ctx, newFunc, newArgs, expr.Source);

            // __slice(ptr,len) helper: represent a "slice" (ptr+len) in the IR.
            // Semantics: evaluate both arguments, result type is the pointer/array (same as arg0).
            // Bounds checks are injected only with -Zcheck (see Program.CheckSliceBounds).
            // Note: keep the intrinsic name conservative to avoid collisions ("slice" is allowed only
            // when there is no declared function named "slice").
            if (newFunc.Match(Tag.Name, out string __sfname))
            {
                bool isSliceIntrinsic = (__sfname == "__slice") || (__sfname == "slice" && ctx.FindFuncParams("slice") == null);
                if (isSliceIntrinsic)
                {
                    if (newArgs.Length != 2)
                    {
                        Program.Error(expr.Source, ErrorCode.ParseError, "{0}: expected 2 arguments: __slice(ptr,len)", __sfname);
                    }
                    else
                    {
                        CType pty = InferType(ctx, newArgs[0]);
                        if (pty == null || !(pty.IsPointer || pty.IsArray))
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: first argument must be a pointer or array, got: {1}", __sfname, (pty == null ? "<unknown>" : pty.Show()));

                        CType lty = InferType(ctx, newArgs[1]);
                        if (lty == null || !lty.IsInteger)
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: second argument must be an integer length, got: {1}", __sfname, (lty == null ? "<unknown>" : lty.Show()));
                    }

                    return Expr.Make(Tag.Slice, newArgs[0], newArgs[1]).WithSource(expr.Source);
                }
            }

            return MakeCall(newFunc, newArgs).WithSource(expr.Source);
        }

Copie exactement 32 octets de src vers dst, sans argument de longueur. Utilisez cet appel pour un enregistrement fixe de 32 octets ou deux motifs de tuile contigus de 16 octets en mémoire accessible au processeur. La copie avance octet par octet ; ce n’est ni une lecture unique sur 32 bits ni un transfert avec changement de banque.

Syntaxe

void __copy32(u8* dst, const u8* src);

Paramètres

dst

Pointeur vers le premier octet accessible en écriture de la destination. Prévoyez une zone contiguë assez grande pour toute l’opération ; aucun tampon n’est alloué automatiquement.

src

Pointeur vers le premier octet lisible de la source. Toute la zone doit rester accessible et inchangée pendant la copie.

Valeur renvoyée

Aucune (void).

Conditions et limites

Utilisez des zones source et destination sans chevauchement. Ces routines copient vers les adresses croissantes et n’offrent pas la sécurité de memmove en cas de recouvrement ; écraser une partie de la source encore non lue peut altérer la suite de la copie.

L’opération se termine avant de rendre la main. Elle ne change pas de banque ROM/RAM et ne limite pas automatiquement la zone aux bornes d’un tampon. Maintenez le mappage stable, utilisez des zones valides et coordonnez l’accès avec les interruptions utilisant les mêmes tampons.

Sur FC, dst est une adresse CPU, pas une adresse PPU. Une copie en RAM CPU ne modifie ni CHR, ni les tables de noms, ni les palettes ; leur chargement nécessite les API PPU/VRAM. Les routines auxiliaires générées partagent les arguments et les temporaires : ne les rappelez pas depuis une NMI/IRQ pendant une opération en cours.

Exemple d’utilisation

memory_reset();
__copy32(memory_destination+1,memory_source+1);
memory_copy_32=memory_check(32,0);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet exemple utilise __copy32 pour copier 32 octets suivant un motif connu à partir du décalage 1. memory_check compare les tableaux source et destination en entier ; la ligne COPY32 doit afficher 032. Le premier octet sert de garde et les octets suivant le bloc doivent également rester inchangés.

Le programme complet initialise deux tampons de 264 octets avant chaque opération, puis vérifie tous les octets de la source, de la destination et des zones de garde. L’écran attendu affiche COPY WORD 257, FILL WORD 257, COPY BYTE 255, FILL BYTE 255, COPY16 016, COPY32 032, ZERO CALLS 002 et FAILED 000. WORD/BYTE désignent la largeur du compteur, pas la taille des éléments copiés. Ces nombres proviennent des vérifications de l’exemple ; ces fonctions void ne renvoient aucune valeur.

Les captures montrent du texte noir sur blanc sur DMG, bleu sur blanc sur CGB et bleu sur noir sur FC. L’exemple vérifie des opérations en RAM ; le texte en présente les résultats, sans illustrer une primitive de dessin. Des contrôles distincts sur émulateur couvrent 88 cas par plateforme : longueurs constantes ou déterminées à l’exécution de 0, 1, 16, 17, 32, 33, 64, 65 et 255 octets, plus 256 et 257 pour les compteurs sur 16 bits. Aucun test sur matériel réel n’a été effectué.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\memory_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\memory_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Copy exactly 32 bytes forward; bank selection and source lifetime belong to the caller.

case "__copy32":
                    if (!Need(2)) return true;
                    EmitFixedMemcpy(args[0], args[1], 32, ctx); return true;
                // Geometry helpers receive byte coordinates; the size array describes ABI packing, not result width.

void EmitFixedMemcpy(Expr dstExpr, Expr srcExpr, int len, FunctionContext ctx)
        {
            int[] ptr = AcquireTemps(4);
            try
            {
                EmitLoadValue(dstExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitLoadValue(srcExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[2]));
                EmitAsm("STX", Mem(ptr[3]));
                for (int i = 0; i < len; i++)
                {
                    EmitAsm("LDY", Imm(i));
                    EmitAsm("LDA", IndY(ptr[2]));
                    EmitAsm("STA", IndY(ptr[0]));
                }
            }
            finally { ReleaseTemps(ptr); }
        }

// kitaqfc/kitaqfc/Lowerer.cs:2128
if (expr.MatchAny(Tag.Call, out callFunc, out callArgs))
        {
            string knownCallName;
            if (callFunc != null && callFunc.Match(Tag.Name, out knownCallName) &&
                knownCallName == "__cgb_is_cgb" &&
                callArgs != null && callArgs.Length == 0 &&
                // A resolved target configuration can replace the zero-argument CGB query with a literal.
                Program.TryGetKnownCgbRuntimeValue(out int knownCgbValue))
            {
                return Expr.Make(Tag.Integer, knownCgbValue).WithSource(expr.Source);
            }

            Expr newFunc = LowerExpr(ctx, callFunc, false, prefix);

            // Optimization (post-A3): when we must spill a non-atomic argument into a temp,
            // prefer a u8 temp if the *parameter type* is u8-like.
            // This preserves semantics (implicit truncation to u8) while avoiding needless
            // u16 temporaries created by integer promotions.
            CType[] paramTypes = null;
            string __fname = null;
            if (newFunc.Match(Tag.Name, out __fname))
            {
                paramTypes = ctx.FindFuncParams(__fname);
                if (paramTypes == null)
                {
                    CType fnTypeFromName;
                    if (TryGetCallableFunctionType(ctx.FindTypeOfName(__fname), out fnTypeFromName))
                        paramTypes = fnTypeFromName.ParamTypes;
                }
            }
            else
            {
                CType fnTypeFromExpr;
                if (TryGetCallableFunctionType(InferType(ctx, newFunc), out fnTypeFromExpr))
                    paramTypes = fnTypeFromExpr.ParamTypes;
            }

            Expr[] newArgs = new Expr[callArgs.Length];
            for (int i = 0; i < callArgs.Length; i++)
            {
                Expr a = LowerExpr(ctx, callArgs[i], allowExtract, prefix);

                bool preserveConstantArgIntrinsic = false;
                if (a.MatchAny(Tag.Call, out Expr argFunc, out Expr[] _argCallArgs) &&
                    argFunc.Match(Tag.Name, out string argFuncName))
                {
                    preserveConstantArgIntrinsic = (argFuncName == "__bankof" || argFuncName == "__cgb_is_cgb");
                }
                // Keep evaluable constants and special intrinsic/bank operands visible to code generation instead of spilling them.
                bool preserveCompileTimeConstantArg = ctx.Global.TryEvalConstInt(a, out _);
                bool preserveFarcallBankArg = (__fname == "__farcall" && i == 0);

                if (allowExtract && !preserveFarcallBankArg && !preserveConstantArgIntrinsic && !preserveCompileTimeConstantArg && !IsAtom(a))
                {
                    // If we know the callee's parameter type, use it to choose a smaller temp.
                    // Example: (u8)(row*32) passed to a u8 param should spill as u8, not u16.
                    CType spillAs = null;
                    if (paramTypes != null && i < paramTypes.Length)
                    {
                        CType pt = paramTypes[i];
                        if (IsU8Like(pt)) spillAs = CType.UInt8;
                    }
                    if (spillAs == null) spillAs = InferType(ctx, a);
                    if (!IsAggregateType(spillAs) && SizeOfType(spillAs) <= 2)
                        a = SpillToTemp(ctx, a, spillAs, prefix);
                }
                newArgs[i] = a;
            }

            // Lint: const discard for argument passing
            // Warn when passing a const-qualified pointer (or const array decay) to a non-const pointer parameter.
            // Suppress when the argument has an explicit cast, or inside __unsafe.
            if (!ctx.InUnsafe && paramTypes != null)
            {
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;
                    if (!IsPointerToNonConst(pt)) continue;
                    if (HasTopLevelCast(newArgs[i])) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at != null && (IsPointerToConst(at) || IsArrayOfConst(at)))
                    {
                        string fn = __fname ?? "<call>";
                        WarnConstDiscard(expr, $"argument {i} to '{fn}'");
                        break; // keep it quiet: one warning per call is enough
                    }
                }
            }

            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    FilePosition argPos = newArgs[i].Source;
                    if (string.IsNullOrEmpty(argPos.Filename) || argPos.Filename == "<unknown>")
                        argPos = expr.Source;
                    WarnImplicitNarrowingIfNeeded(ctx, newArgs[i], InferType(ctx, newArgs[i]), paramTypes[i], argPos,
                        "argument " + i + " to '" + fn + "'");
                }
            }

            // Lint: __enum_strict argument passing.
            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at == null) continue;

                    if (HasTopLevelCast(newArgs[i])) continue;

                    if (IsStrictEnum(pt))
                    {
                        if (!IsSameEnum(pt, at))
                        {
                            Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                                "argument {0} to '{1}' expects __enum_strict {2}, got {3}; cast explicitly to silence",
                                i, fn, pt.Show(), at.Show());
                        }
                    }
                    else if (IsPlainInteger(pt) && IsStrictEnum(at))
                    {
                        Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                            "argument {0} to '{1}' passes __enum_strict {2} to integer parameter {3}; cast explicitly to silence",
                            i, fn, at.Show(), pt.Show());
                    }
                }
            }

            if (!ctx.InUnsafe)
                RestrictAliasLint(ctx, newFunc, newArgs, expr.Source);

            // __slice(ptr,len) helper: represent a "slice" (ptr+len) in the IR.
            // Semantics: evaluate both arguments, result type is the pointer/array (same as arg0).
            // Bounds checks are injected only with -Zcheck (see Program.CheckSliceBounds).
            // Note: keep the intrinsic name conservative to avoid collisions ("slice" is allowed only
            // when there is no declared function named "slice").
            if (newFunc.Match(Tag.Name, out string __sfname))
            {
                bool isSliceIntrinsic = (__sfname == "__slice") || (__sfname == "slice" && ctx.FindFuncParams("slice") == null);
                if (isSliceIntrinsic)
                {
                    if (newArgs.Length != 2)
                    {
                        Program.Error(expr.Source, ErrorCode.ParseError, "{0}: expected 2 arguments: __slice(ptr,len)", __sfname);
                    }
                    else
                    {
                        CType pty = InferType(ctx, newArgs[0]);
                        if (pty == null || !(pty.IsPointer || pty.IsArray))
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: first argument must be a pointer or array, got: {1}", __sfname, (pty == null ? "<unknown>" : pty.Show()));

                        CType lty = InferType(ctx, newArgs[1]);
                        if (lty == null || !lty.IsInteger)
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: second argument must be an integer length, got: {1}", __sfname, (lty == null ? "<unknown>" : lty.Show()));
                    }

                    return Expr.Make(Tag.Slice, newArgs[0], newArgs[1]).WithSource(expr.Source);
                }
            }

            return MakeCall(newFunc, newArgs).WithSource(expr.Source);
        }

Calcule un produit scalaire non signé à deux termes.

Syntaxe

u16 __dot2_q8_8(u16 a0, u16 a1, u8 b0, u8 b1);

Paramètres

a0

Mot non signé de 0 à 65535.

a1

Mot non signé de 0 à 65535.

b0

Coefficient non signé de 0 à 255.

b1

Coefficient non signé de 0 à 255.

Valeur renvoyée

Renvoie les 16 bits de poids faible de a0*b0+a1*b1.

Conditions et limites

Sur FC, les fonctions nommées q8_8/q1_7 utilisent les produits entiers bruts, sans décalage de mise à l’échelle fixe. Les fonctions Q1.7 sont des alias des opérations signées correspondantes. L’appelant gère les unités ; les résultats signés sont renvoyés comme motifs de bits u16.

Exemple d’utilisation

// Compare literal coefficients with values read from RAM.
result[22]=__dot2_q8_8(513,769,64,127);
v0=513;v1=769;v2=64;v3=127;
result[23]=__dot2_q8_8(v0,v1,v2,v3);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Comparez les entrées littérales aux valeurs en RAM. Les résultats représentatifs sont affichés sur 16 bits non signés ; les négatifs utilisent le complément à deux. Le GB remet à l’échelle les produits à virgule fixe, tandis que le FC renvoie des produits entiers : des entrées identiques ne donnent donc pas nécessairement les mêmes résultats.

L’extrait stocke les valeurs suivantes sur 16 bits : result[22]=64959, result[23]=64959. Chaque calcul avec une entrée littérale correspond à son équivalent avec une entrée en RAM. L’écran affiche des valeurs représentatives ; le tableau result conserve tous les résultats.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch3_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return a0*b0+a1*b1 modulo 65536. The FC backend inserts no Q8.8 rescaling or rounding.

case "__dot2_q8_8": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,2,1,1}, funcName);

void EmitHelperMath()
        {
            // Consume eight multiplier bits and accumulate the low product word in shared temporaries, returning A/X.
            EmitHelperStart("__mul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDX", Imm(8));
            string loop = NewGeneratedLabel("mul16x8_loop");
            string skip = NewGeneratedLabel("mul16x8_skip_add");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LSR", Mem(CallArgBase + 2));
            EmitAsm("BCC", Rel(skip));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("ADC", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, skip));
            EmitAsm("ASL", Mem(CallArgBase));
            EmitAsm("ROL", Mem(CallArgBase + 1));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(loop));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            // Zero-extend the byte multiplicand, reuse word multiplication and return its high byte.
            EmitHelperStart("__mul8x8_hi");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("TXA");
            EmitAsm("RTS");

            // Convert signed operands to magnitudes, multiply, then restore the product sign modulo 65536.
            EmitHelperStart("__smul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            string aPos = NewGeneratedLabel("smul_a_positive");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(aPos));
            EmitAsm("LDA", Mem(CallArgBase)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("LDA", Mem(CallArgBase + 1)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, aPos));
            string bPos = NewGeneratedLabel("smul_b_positive");
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(bPos));
            EmitAsm("LDA", Mem(CallArgBase + 2)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, bPos));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STX", Mem(_runtimeIntrinsicTmp1Address));
            string sdone = NewGeneratedLabel("smul_done");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("BEQ", Rel(sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            EmitMacHelper("__mac16", "__mul16x8");
            EmitMacHelper("__smac16", "__smul16x8");
            EmitDot2Helper("__dot2_q8_8", "__mul16x8");
            EmitDot3Helper("__dot3_q8_8", "__mul16x8");
            EmitDot2Helper("__sdot2_q8_8", "__smul16x8");
            EmitDot3Helper("__sdot3_q8_8", "__smul16x8");
        }

Calcule un produit scalaire non signé à trois termes.

Syntaxe

u16 __dot3_q8_8(u16 a0, u16 a1, u16 a2, u8 b0, u8 b1, u8 b2);

Paramètres

a0

Mot non signé de 0 à 65535.

a1

Mot non signé de 0 à 65535.

a2

Mot non signé de 0 à 65535.

b0

Coefficient non signé de 0 à 255.

b1

Coefficient non signé de 0 à 255.

b2

Coefficient non signé de 0 à 255.

Valeur renvoyée

Renvoie les 16 bits de poids faible de a0*b0+a1*b1+a2*b2.

Conditions et limites

Sur FC, les fonctions nommées q8_8/q1_7 utilisent les produits entiers bruts, sans décalage de mise à l’échelle fixe. Les fonctions Q1.7 sont des alias des opérations signées correspondantes. L’appelant gère les unités ; les résultats signés sont renvoyés comme motifs de bits u16.

Exemple d’utilisation

// Compare literal coefficients with values read from RAM.
result[24]=__dot3_q8_8(513,769,1025,64,127,3);
v0=513;v1=769;v2=1025;v3=64;v4=127;v5=3;
result[25]=__dot3_q8_8(v0,v1,v2,v3,v4,v5);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Comparez les entrées littérales aux valeurs en RAM. Les résultats représentatifs sont affichés sur 16 bits non signés ; les négatifs utilisent le complément à deux. Le GB remet à l’échelle les produits à virgule fixe, tandis que le FC renvoie des produits entiers : des entrées identiques ne donnent donc pas nécessairement les mêmes résultats.

L’extrait stocke les valeurs suivantes sur 16 bits : result[24]=2498, result[25]=2498. Chaque calcul avec une entrée littérale correspond à son équivalent avec une entrée en RAM. L’écran affiche des valeurs représentatives ; le tableau result conserve tous les résultats.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch3_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Sum three unsigned word-by-byte products modulo 65536 without a final scaling shift.

case "__dot3_q8_8": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,2,2,1,1,1}, funcName);

void EmitHelperMath()
        {
            // Consume eight multiplier bits and accumulate the low product word in shared temporaries, returning A/X.
            EmitHelperStart("__mul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDX", Imm(8));
            string loop = NewGeneratedLabel("mul16x8_loop");
            string skip = NewGeneratedLabel("mul16x8_skip_add");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LSR", Mem(CallArgBase + 2));
            EmitAsm("BCC", Rel(skip));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("ADC", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, skip));
            EmitAsm("ASL", Mem(CallArgBase));
            EmitAsm("ROL", Mem(CallArgBase + 1));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(loop));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            // Zero-extend the byte multiplicand, reuse word multiplication and return its high byte.
            EmitHelperStart("__mul8x8_hi");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("TXA");
            EmitAsm("RTS");

            // Convert signed operands to magnitudes, multiply, then restore the product sign modulo 65536.
            EmitHelperStart("__smul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            string aPos = NewGeneratedLabel("smul_a_positive");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(aPos));
            EmitAsm("LDA", Mem(CallArgBase)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("LDA", Mem(CallArgBase + 1)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, aPos));
            string bPos = NewGeneratedLabel("smul_b_positive");
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(bPos));
            EmitAsm("LDA", Mem(CallArgBase + 2)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, bPos));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STX", Mem(_runtimeIntrinsicTmp1Address));
            string sdone = NewGeneratedLabel("smul_done");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("BEQ", Rel(sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            EmitMacHelper("__mac16", "__mul16x8");
            EmitMacHelper("__smac16", "__smul16x8");
            EmitDot2Helper("__dot2_q8_8", "__mul16x8");
            EmitDot3Helper("__dot3_q8_8", "__mul16x8");
            EmitDot2Helper("__sdot2_q8_8", "__smul16x8");
            EmitDot3Helper("__sdot3_q8_8", "__smul16x8");
        }

__exp_pad_read1 appelle la même routine du compilateur que __pad_read1_d1. Il lit D1 à $4016 avec la même séquence de verrouillage, le même résultat de huit bits et les mêmes effets de bord. Ce nom indique l’usage pour l’extension ; il n’active aucun autre mode de périphérique et ne combine pas D0 et D1.

Syntaxe

u8 __exp_pad_read1(void);

Valeur renvoyée

Masque de maintien de 8 bits dans l’ordre NES. Chaque bit à 1 identifie un bouton appuyé ; 0 signifie aucun. Ce n’est pas un booléen normalisé.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Utilisez un périphérique fournissant un flux série de manette compatible sur huit bits par la ligne D1 choisie. La fonction n’identifie pas le périphérique et ne prend pas en charge tous les protocoles d’extension. Chaque appel verrouille à nouveau les deux flux de contrôleurs ; terminez une lecture complète avant d’en commencer une autre. Les résultats sont de nouvelles lectures qui ne mettent pas à jour les états input_* ou nes_pad1_*.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Exemple d’utilisation

expansion_first=__exp_pad_read1(); // Same helper as __pad_read1_d1.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare l’entrée ordinaire D0, l’extension D1 et le niveau numérique du microphone. Maintenez A sur la manette 1 et B sur la manette 2 jusqu’à la capture. NORMAL P1 et NORMAL P2 affichent 001 et 002. Dans l’exécution KUROSAKI fournie, D1 PORT 1, D1 PORT 2, EXP ALIAS 1, EXP ALIAS 2, MIC LEVEL et MIC DIRECT affichent 000, car ces lignes ne sont pas émulées. Les valeurs restent ensuite fixes. Avec des périphériques adaptés et leurs lignes implémentées, les valeurs dépendent des entrées réelles ; interprétez-les selon les bits décrits ci-dessus au lieu d’attendre ces zéros.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\expansion_input.c -I .\kitaq-docs\samples -I .\kitaqfc\lib -o .\out\expansion_input.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Alias the port-1 D1 controller reader; the attached device must use the expected serial protocol.

__exp_pad_read2 appelle la même routine du compilateur que __pad_read2_d1. Il lit D1 à $4017 avec la même séquence de verrouillage, le même résultat de huit bits et les mêmes effets de bord. Ce nom indique l’usage pour l’extension ; il n’active aucun autre mode de périphérique et ne combine pas D0 et D1.

Syntaxe

u8 __exp_pad_read2(void);

Valeur renvoyée

Masque de maintien de 8 bits dans l’ordre NES. Chaque bit à 1 identifie un bouton appuyé ; 0 signifie aucun. Ce n’est pas un booléen normalisé.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Utilisez un périphérique fournissant un flux série de manette compatible sur huit bits par la ligne D1 choisie. La fonction n’identifie pas le périphérique et ne prend pas en charge tous les protocoles d’extension. Chaque appel verrouille à nouveau les deux flux de contrôleurs ; terminez une lecture complète avant d’en commencer une autre. Les résultats sont de nouvelles lectures qui ne mettent pas à jour les états input_* ou nes_pad1_*.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Exemple d’utilisation

expansion_second=__exp_pad_read2(); // Same helper as __pad_read2_d1.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare l’entrée ordinaire D0, l’extension D1 et le niveau numérique du microphone. Maintenez A sur la manette 1 et B sur la manette 2 jusqu’à la capture. NORMAL P1 et NORMAL P2 affichent 001 et 002. Dans l’exécution KUROSAKI fournie, D1 PORT 1, D1 PORT 2, EXP ALIAS 1, EXP ALIAS 2, MIC LEVEL et MIC DIRECT affichent 000, car ces lignes ne sont pas émulées. Les valeurs restent ensuite fixes. Avec des périphériques adaptés et leurs lignes implémentées, les valeurs dépendent des entrées réelles ; interprétez-les selon les bits décrits ci-dessus au lieu d’attendre ces zéros.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\expansion_input.c -I .\kitaq-docs\samples -I .\kitaqfc\lib -o .\out\expansion_input.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Alias the port-2 D1 controller reader; this is not an expansion-device discovery operation.

Sélectionne temporairement une banque ROM, copie len octets de src vers dst par adresses croissantes, puis rétablit la banque mémorisée par le compilateur. Sur cette plateforme, __farmemcpy et __far_memcpy utilisent la même implémentation.

Syntaxe

void __far_memcpy(u8* dst, u8 bank, u16 src, u16 len);

Paramètres

dst

Destination en mémoire accessible en écriture, assez grande pour tous les octets copiés. Hors transfert de zéro octet, les adresses nulles ou invalides ne sont pas vérifiées.

bank

Sélecteur de banque sur 8 bits pour la ROM source. Utilisez une banque compatible avec la cartouche et l’organisation du compilateur ; ce paramètre est distinct de l’adresse source.

src

Adresse CPU sur 16 bits des données dans le mappage ROM sélectionné. La déclaration FC attend un u16 ; convertissez le pointeur avec (u16)pointer.

len

Nombre d’octets, de 0 à 65535. Avec zéro, aucune mémoire n’est copiée, mais la sélection et le rétablissement de la banque ont bien lieu.

Valeur renvoyée

Aucune (void).

Conditions et limites

Toute la source doit être lisible dans le mappage ROM prévu, et toute la destination accessible en écriture. La copie ne passe pas automatiquement à la banque suivante, ne gère pas les chevauchements comme memmove et ne synchronise pas les écritures VRAM. Utilisez les API graphiques pour la VRAM.

Les exemples placent le code appelant dans la banque fixe 0 afin qu’un changement de banque source ne le rende pas inaccessible. Les transferts sont synchrones. N’interrompez pas un transfert par une autre copie changeant de banque ; cette fonction ne garantit pas à elle seule la sûreté des interruptions de toute l’application.

Exemple d’utilisation

__far_memcpy(buffer,payload_bank,(u16)payload_pointer,32);
expect(*asset_bank_marker==0xA1 && bank_get_current()==1,27);
for(i=0;i<32;i++) expect(buffer[(__safe_index u8)i]==expected_shape_byte(i),28);
buffer[32]=0x55;
__far_memcpy(buffer+32,2,(u16)asset_shapes,0);
expect(buffer[32]==0x55 && *asset_bank_marker==0xA1,30);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Copie deux motifs, soit 32 octets, depuis la banque 2 alors que la banque 1 est sélectionnée au départ. Le programme compare tous les octets, vérifie le retour à la banque 1 et la conservation du témoin 0x55 lors d’une copie de longueur nulle.

Image attendue : une rangée rouge part de (16,32) et occupe 72×8 pixels. Elle répète trois fois un triangle de 8×8, un carré de 8×8 au contour d’un pixel et une tuile dont les quatre colonnes de gauche sont pleines. Le triangle s’élargit d’un pixel en haut à gauche à huit sur sa ligne inférieure.

Sur FC, la paire bleue en (16,64) montre __far_memcpy ; la verte en (16,96), asset_load_raw suivi d’un transfert en CHR. Chaque paire occupe 16×8 pixels sur fond noir. Ces rangées montrent les données graphiques copiées, pas seulement des valeurs d’état numériques.

L’état attendu est FAILED CHECKS 000 et FIRST FAILURE 00. La vérification exécute 300 images puis compare texte, formes et couleurs aux résultats attendus. Il s’agit d’une preuve sur émulateur, pas d’un essai sur matériel physique.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Switch to the source bank, copy len bytes forward and restore the previous bank.
Keep destination RAM and helper code accessible throughout; overlapping copies are not memmove.

Appelle une fonction nommée sans argument. Le compilateur FC utilise sa banque d’affectation pour choisir un appel direct ou une routine qui restaure la banque. L’argument bank est évalué, mais le placement de la fonction détermine la sélection.

Syntaxe

__farcall(bank, function_name);

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

func

Nom déclaré d’une fonction sans paramètre. Cet appel intrinsèque par nom n’accepte pas une variable contenant une adresse de fonction. L’argument bank n’est pas transmis au rappel.

Valeur renvoyée

Le résultat suit le type de la fonction appelée. Un rappel void ne renvoie rien ; les rappels u8 et u16 renvoient leur valeur scalaire. L’exemple affiché utilise des rappels void.

Conditions et limites

Ces appels ne transmettent pas d’arguments utilisateur et ne rendent pas le rappel réentrant face aux interruptions. Gérez correctement ses données, sa pile et ses interruptions. La restauration des banques est testée avec des appels imbriqués et répétés ; l’exemple ne couvre ni le matériel physique ni tous les entrelacements d’interruptions.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

__farcall(3,callback);
bank_expect(callback_count==2 && callback_byte==0xD3,16);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

À ce stade du programme complet, __farcall porte callback_count à 2. Le rappel lit D3 dans la banque 3. Une lecture proche ultérieure de B2 dans home2 confirme le retour avec la banque 2 sélectionnée.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Call a declared zero-argument function; placement selects its bank and its declared type determines the result.

if (string.Equals(funcName, "__farcall", StringComparison.Ordinal))
            {
                Expr[] farArgs = args ?? Array.Empty<Expr>();
                if (farArgs.Length != 2)
                {
                    Program.Error("error KQ0000: __farcall(bank, func) expects exactly 2 arguments.");
                    return;
                }

                string targetName;
                if (!farArgs[1].Match(Tag.Name, out targetName))
                {
                    Program.Error("error KQ0000: __farcall(bank, func) requires the 2nd argument to be a function name.");
                    return;
                }
                // This intrinsic supplies no callback arguments. A variable name
                // is not a static function target, even when its value is a pointer.
                if (!_functionParameters.TryGetValue(targetName, out FieldInfo[] farParameters))
                {
                    Program.Error("error KQFC2610: __farcall requires a declared function name; use an ordinary typed call for a function pointer.");
                    return;
                }
                if (farParameters.Length != 0)
                {
                    Program.Error("error KQFC2610: __farcall requires a callback with no parameters.");
                    return;
                }
                if (Program.NesMapperProfile.IsSurom512 &&
                    TryEvaluateConstant(farArgs[0], out int constantFarBank) &&
                    (constantFarBank < 1 || constantFarBank > 30))
                {
                    Program.Error("error KQFC2603 KQFC-SUROM-BANK-RANGE: __farcall constant bank {0} is outside 1..30; common bank 0 is not a switch target.", constantFarBank);
                    return;
                }

                // Evaluate the requested far-call bank byte; the following dispatch uses the target function bank metadata.
                EmitLoadValue(farArgs[0], ctx, 1);

                int callerBank = ctx == null ? 0 : ctx.Bank;
                int calleeBank = GetFunctionBank(targetName);
                if (ShouldUseFdsOverlayThunk(callerBank, calleeBank))
                {
                    string fdsThunkName = EnsureFdsOverlayThunk(targetName, calleeBank);
                    EmitAsm("JSR", Abs(fdsThunkName));
                    RecordCallEdge(targetName, calleeBank, "fds_overlay_thunk", viaThunk: true, viaFarcall: true);
                    return;
                }
                bool bankedPrg = Program.NesMapperProfile.SupportsPrgBanking || Program.NesMapperProfile.UsesDuplicatedCommonBank;
                bool directSafe = !bankedPrg || calleeBank == 0 || calleeBank == callerBank;
                if (directSafe)
                {
                    EmitAsm("JSR", Abs(targetName));
                    RecordCallEdge(targetName, calleeBank, "direct", viaThunk: false, viaFarcall: true);
                    return;
                }

                string thunkName = EnsureBankThunk(targetName, calleeBank);
                EmitAsm("JSR", Abs(thunkName));
                RecordCallEdge(targetName, calleeBank, "bank_thunk", viaThunk: true, viaFarcall: true);
                return;
            }

__farmemcpy est une autre orthographe de l’intrinsèque FC __far_memcpy. Les arguments et la routine de copie avec restauration de la banque sont identiques ; cette orthographe ne change ni la méthode ni la vitesse du transfert. L’exemple l’utilise pour lire des motifs de tuiles en ROM et les copier en RAM.

Sélectionne temporairement une banque ROM, copie len octets de src vers dst par adresses croissantes, puis rétablit la banque mémorisée par le compilateur. Sur cette plateforme, __farmemcpy et __far_memcpy utilisent la même implémentation.

Syntaxe

void __farmemcpy(u8* dst, u8 bank, u16 src, u16 len);

Paramètres

dst

Destination en mémoire accessible en écriture, assez grande pour tous les octets copiés. Hors transfert de zéro octet, les adresses nulles ou invalides ne sont pas vérifiées.

bank

Sélecteur de banque sur 8 bits pour la ROM source. Utilisez une banque compatible avec la cartouche et l’organisation du compilateur ; ce paramètre est distinct de l’adresse source.

src

Adresse CPU sur 16 bits des données dans le mappage ROM sélectionné. La déclaration FC attend un u16 ; convertissez le pointeur avec (u16)pointer.

len

Nombre d’octets, de 0 à 65535. Avec zéro, aucune mémoire n’est copiée, mais la sélection et le rétablissement de la banque ont bien lieu.

Valeur renvoyée

Aucune (void).

Conditions et limites

Le compilateur enregistre directement cette orthographe ; vous pouvez donc l’appeler sans déclaration distincte dans intrinsics.h. Les arguments sont, dans l’ordre, un pointeur RAM, un numéro de banque sur 8 bits, une adresse CPU sur 16 bits et un nombre d’octets sur 16 bits. src n’est pas un décalage depuis le début du fichier ROM.

Toute la source doit être lisible dans le mappage ROM prévu, et toute la destination accessible en écriture. La copie ne passe pas automatiquement à la banque suivante, ne gère pas les chevauchements comme memmove et ne synchronise pas les écritures VRAM. Utilisez les API graphiques pour la VRAM.

Les exemples placent le code appelant dans la banque fixe 0 afin qu’un changement de banque source ne le rende pas inaccessible. Les transferts sont synchrones. N’interrompez pas un transfert par une autre copie changeant de banque ; cette fonction ne garantit pas à elle seule la sûreté des interruptions de toute l’application.

Lorsque len vaut zéro, aucun octet de destination n’est modifié, mais la sélection et la restauration de la banque ont tout de même lieu. La fonction ne renvoie aucune valeur.

__far_memcpy

Exemple d’utilisation

__farmemcpy(buffer,payload_bank,(u16)payload_pointer,32);
expect(*asset_bank_marker==0xA1 && bank_get_current()==1,27);
for(i=0;i<32;i++) expect(buffer[(__safe_index u8)i]==expected_shape_byte(i),28);
buffer[32]=0x55;
__farmemcpy(buffer+32,2,(u16)asset_shapes,0);
expect(buffer[32]==0x55 && *asset_bank_marker==0xA1,30);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Copie deux motifs, soit 32 octets, depuis la banque 2 alors que la banque 1 est sélectionnée au départ. Le programme compare tous les octets, vérifie le retour à la banque 1 et la conservation du témoin 0x55 lors d’une copie de longueur nulle.

Image attendue : une rangée rouge part de (16,32) et occupe 72×8 pixels. Elle répète trois fois un triangle de 8×8, un carré de 8×8 au contour d’un pixel et une tuile dont les quatre colonnes de gauche sont pleines. Le triangle s’élargit d’un pixel en haut à gauche à huit sur sa ligne inférieure.

Le triangle et le contour carré bleus au pixel (16,64) affichent les octets copiés par __farmemcpy. La paire verte en dessous, en (16,96), provient de asset_load_raw. Chaque paire occupe 16×8 pixels sur fond noir ; les octets copiés sont transférés en CHR RAM pour l’affichage.

L’état attendu est FAILED CHECKS 000 et FIRST FAILURE 00. La vérification exécute 300 images puis compare texte, formes et couleurs aux résultats attendus. Il s’agit d’une preuve sur émulateur, pas d’un essai sur matériel physique.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\far_copy_alias.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\far_copy_alias.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

case "__far_memcpy":
                case "__farmemcpy":
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,1,2,2}, "__far_memcpy");

Lit une valeur de 16 bits little-endian en addr et addr+1 après une sélection temporaire de banque, puis rétablit la banque précédente. C’est l’intrinsèque utilisée par far_data_read16.

Syntaxe

u16 __farpeek16(u8 bank, u16 addr);

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

addr

Adresse CPU sur 16 bits des données dans le mappage ROM sélectionné. La déclaration FC attend un u16 ; convertissez le pointeur avec (u16)pointer.

Valeur renvoyée

Le mot little-endian lu, sous forme de u16 (0–65535).

Conditions et limites

L’octet ou le mot entier doit être lisible dans le mappage CPU sélectionné. Ces lectures ne valident pas les pointeurs, ne bornent pas les adresses et ne passent pas automatiquement à une autre banque à la limite d’une fenêtre. Un mot exige deux octets consécutifs valides.

Les lectures et copies distantes sont synchrones et utilisent un espace de travail partagé du compilateur. Une interruption ne doit pas y exécuter un autre transfert pendant son utilisation. Sur GB, la copie utilise aussi un emplacement HRAM partagé pour la banque sauvegardée. L’exemple exécute ces opérations depuis du code fixe, sans gestionnaire de transfert concurrent.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

bank_expect(__farpeek16(3,(u16)(payload+1))==0x5C7A,14);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet extrait utilise __farpeek16 pour lire payload+1 dans la banque 3 et vérifie 5C7A. Le programme complet lit aussi home2 avec un pointeur proche pour confirmer la restauration de la banque 2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Temporarily select bank and read a little-endian word, then restore the previous mapping.

EmitHelperStart("__farpeek16");
            // args: bank, addr16. Return A=lo, X=hi.
            EmitAsm("LDA", Mem(_runtimeCurrentBankAddress));
            EmitAsm("PHA");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_prg_set_bank_a"));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", IndY(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("INY");
            EmitAsm("LDA", IndY(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("PLA");
            EmitAsm("JSR", Abs("__kq_prg_set_bank_a"));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            // Consume the word count while advancing source/destination pointers; zero count still restores the saved bank.

Sélectionne temporairement la banque indiquée, lit un octet à l’adresse CPU et rétablit la banque précédente. C’est l’intrinsèque utilisée par far_data_read8.

Syntaxe

u8 __farpeek8(u8 bank, u16 addr);

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

addr

Adresse CPU sur 16 bits des données dans le mappage ROM sélectionné. La déclaration FC attend un u16 ; convertissez le pointeur avec (u16)pointer.

Valeur renvoyée

L’octet lu, sous forme de u8 (0–255).

Conditions et limites

L’octet ou le mot entier doit être lisible dans le mappage CPU sélectionné. Ces lectures ne valident pas les pointeurs, ne bornent pas les adresses et ne passent pas automatiquement à une autre banque à la limite d’une fenêtre. Un mot exige deux octets consécutifs valides.

Les lectures et copies distantes sont synchrones et utilisent un espace de travail partagé du compilateur. Une interruption ne doit pas y exécuter un autre transfert pendant son utilisation. Sur GB, la copie utilise aussi un emplacement HRAM partagé pour la banque sauvegardée. L’exemple exécute ces opérations depuis du code fixe, sans gestionnaire de transfert concurrent.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

bank_expect(__farpeek8(3,(u16)payload)==0xD3,13);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet extrait utilise __farpeek8 pour lire payload dans la banque 3 et vérifie D3. Le programme complet lit aussi home2 avec un pointeur proche pour confirmer la restauration de la banque 2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Temporarily select bank, read one byte at addr and restore the prior bank mapping.

EmitHelperStart("__farpeek8");
            // args: bank, addr16. Return A.
            EmitAsm("LDA", Mem(_runtimeCurrentBankAddress));
            EmitAsm("PHA");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_prg_set_bank_a"));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", IndY(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("PLA");
            EmitAsm("JSR", Abs("__kq_prg_set_bank_a"));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Retain both fetched bytes across bank restoration and return the word in A/X.

Vérifiez le motif de détection du clavier avant d’interpréter les touches enfoncées.

Syntaxe

u8 __fkb_detect(void);

Valeur renvoyée

Renvoie 1 si la ligne 9, colonne 0 donne 0x1E et si la matrice désactivée donne zéro ; sinon, renvoie 0. Il s’agit d’une détection heuristique par motif de signal, pas d’un code d’identification du périphérique.

Conditions et limites

Ces API accèdent directement à $4016/$4017. N’entrelacez pas sur les mêmes ports des opérations de manette, clavier ou série pilotées par interruption. Les positions de décalage des contrôleurs peuvent aussi être affectées. L’exemple désactive la NMI pendant la capture des entrées, puis l’active à l’initialisation de l’affichage.

Écrit 5 dans $4016 pour revenir à la ligne 0, puis avance les lignes par transitions haut-bas du bit de sélection de colonne. Outre les instructions environnantes, le code généré inclut 12 cycles CPU de NOP après la réinitialisation et 50 après la sélection de colonne. Il écrit zéro à la sortie pour désactiver la matrice.

Une vérification de régression distincte examine les lignes 0 à 9, les deux colonnes, le balayage de neuf lignes, les délais de stabilisation et l’état final des ports à partir de traces de bus CPU exécutées. Elle n’injecte aucun signal de touche physique.

La ligne 9 ne contient aucune touche. Une condition non satisfaite provoque un retour immédiat de zéro. KUROSAKI renvoie zéro dès la première lecture ; la détection y échoue donc.

Ces images exécutent les ROM téléchargeables sans modification dans KUROSAKI. Son bus d’entrée modélise les manettes, mais pas les signaux du clavier, du pistolet optique ou d’un adaptateur série. Les bits d’entrée externes se lisent à zéro ; les captures ne valident donc pas ces appareils. Les touches physiques, la détection optique et la communication restent non testées.

NESdev : clavier Family BASIC

Exemple d’utilisation

#include "fc_ports_scene.h"
void main(void){
    u8 row;
    __irq_disable();__ppu_ctrl_set(0);port_phase=1;
    port_result[0]=__fkb_detect();
    __fkb_scan(key_matrix);
    port_result[1]=__fkb_read_row_col(6,0);
    port_result[2]=0;
    if(port_result[0] && !(port_result[1]&16))port_result[2]=1;
    port_phase=2;port_result[31]=165;
    m_init();m_text(2,2,"KEYBOARD STARTUP SNAPSHOT");m_wait();
    m_text(2,4,"DEVICE DETECT");port_number(25,4,port_result[0]);m_wait();
    m_text(2,6,"ROW 6 COL 0");port_number(25,6,port_result[1]);m_wait();
    m_text(2,8,"A KEY - GUARDED");port_number(25,8,port_result[2]);m_wait();
    m_text(2,10,"ROW   COL0  COL1  (HEX)");m_wait();
    for(row=0;row<9;row++){
        m_put(3,12+row,'0'+row);port_hex(9,12+row,key_matrix[row*2]);port_hex(15,12+row,key_matrix[row*2+1]);m_wait();
    }
    m_text(2,23,"RAW MATRIX - NOT ASCII");m_wait();
    while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Dans cette exécution KUROSAKI, DEVICE DETECT, ROW 6 COL 0 et A KEY - GUARDED valent tous 000 ; les neuf paires COL0/COL1 valent 00. A se trouve ligne 6, colonne 0, bit 4, mais l’échec de détection empêche de signaler le zéro brut comme une touche enfoncée. Le tableau est une capture unique au démarrage.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\peripheral_keyboard.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\peripheral_keyboard.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
.\kurosaki\kurosaki.exe run .\out\peripheral_keyboard.nes --frames 120 --png .\out\peripheral_keyboard.png

Family BASIC Keyboard. __fkb_scan() writes 18 bytes: 9 rows x 2 columns,
each byte containing raw $4017 & 0x1E for that row/column.

Probe selected-row and disabled-matrix bit patterns and return 0 or 1; this is a heuristic detection.

EmitHelperStart("__fkb_detect");
            EmitAsm("LDA", Imm(0x09));
            EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("JSR", Abs("__fkb_read_row_col"));
            EmitAsm("CMP", Imm(0x1E));
            string no = NewGeneratedLabel("fkb_no");
            EmitAsm("BNE", Rel(no));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x1E));
            EmitAsm("BNE", Rel(no));
            EmitAsm("LDA", Imm(1));
            EmitAsm("RTS");
            _assembly.Add(Expr.Make(Tag.Label, no));
            EmitAsm("LDA", Imm(0));
            EmitAsm("RTS");

Lisez une seule ligne et un seul groupe de colonnes, sans tampon de 18 octets, lorsque seul ce groupe vous intéresse.

Syntaxe

u8 __fkb_read_row_col(u8 row, u8 col);

Paramètres

row

Utilisez 0..8 pour les lignes de touches, ou 9 pour la ligne de détection sans touche. Aucun contrôle de plage n’est généré à l’exécution.

col

0 ou 1. Seul le bit de poids faible est utilisé : une valeur paire sélectionne le groupe 0, une valeur impaire le groupe 1.

Valeur renvoyée

Renvoie $4017 & 0x1E sans décaler les bits vers les positions de poids faible.

Conditions et limites

Ces API accèdent directement à $4016/$4017. N’entrelacez pas sur les mêmes ports des opérations de manette, clavier ou série pilotées par interruption. Les positions de décalage des contrôleurs peuvent aussi être affectées. L’exemple désactive la NMI pendant la capture des entrées, puis l’active à l’initialisation de l’affichage.

Les groupes de touches sont les bits bruts 1 à 4 : une touche enfoncée efface son bit, et un groupe au repos vaut 0x1E. Ce ne sont ni du texte ASCII ni un masque où un signifie enfoncé. Un appareil débranché peut aussi se lire à zéro ; vérifiez sa présence avant d’interpréter cela comme toutes les touches maintenues.

Écrit 5 dans $4016 pour revenir à la ligne 0, puis avance les lignes par transitions haut-bas du bit de sélection de colonne. Outre les instructions environnantes, le code généré inclut 12 cycles CPU de NOP après la réinitialisation et 50 après la sélection de colonne. Il écrit zéro à la sortie pour désactiver la matrice.

Une vérification de régression distincte examine les lignes 0 à 9, les deux colonnes, le balayage de neuf lignes, les délais de stabilisation et l’état final des ports à partir de traces de bus CPU exécutées. Elle n’injecte aucun signal de touche physique.

Revient à la ligne 0 et avance à nouveau à chaque appel ; la position atteinte lors de l’appel précédent n’est pas réutilisée.

Ces images exécutent les ROM téléchargeables sans modification dans KUROSAKI. Son bus d’entrée modélise les manettes, mais pas les signaux du clavier, du pistolet optique ou d’un adaptateur série. Les bits d’entrée externes se lisent à zéro ; les captures ne valident donc pas ces appareils. Les touches physiques, la détection optique et la communication restent non testées.

NESdev : clavier Family BASIC

Exemple d’utilisation

#include "fc_ports_scene.h"
void main(void){
    u8 row;
    __irq_disable();__ppu_ctrl_set(0);port_phase=1;
    port_result[0]=__fkb_detect();
    __fkb_scan(key_matrix);
    port_result[1]=__fkb_read_row_col(6,0);
    port_result[2]=0;
    if(port_result[0] && !(port_result[1]&16))port_result[2]=1;
    port_phase=2;port_result[31]=165;
    m_init();m_text(2,2,"KEYBOARD STARTUP SNAPSHOT");m_wait();
    m_text(2,4,"DEVICE DETECT");port_number(25,4,port_result[0]);m_wait();
    m_text(2,6,"ROW 6 COL 0");port_number(25,6,port_result[1]);m_wait();
    m_text(2,8,"A KEY - GUARDED");port_number(25,8,port_result[2]);m_wait();
    m_text(2,10,"ROW   COL0  COL1  (HEX)");m_wait();
    for(row=0;row<9;row++){
        m_put(3,12+row,'0'+row);port_hex(9,12+row,key_matrix[row*2]);port_hex(15,12+row,key_matrix[row*2+1]);m_wait();
    }
    m_text(2,23,"RAW MATRIX - NOT ASCII");m_wait();
    while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Dans cette exécution KUROSAKI, DEVICE DETECT, ROW 6 COL 0 et A KEY - GUARDED valent tous 000 ; les neuf paires COL0/COL1 valent 00. A se trouve ligne 6, colonne 0, bit 4, mais l’échec de détection empêche de signaler le zéro brut comme une touche enfoncée. Le tableau est une capture unique au démarrage.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\peripheral_keyboard.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\peripheral_keyboard.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
.\kurosaki\kurosaki.exe run .\out\peripheral_keyboard.nes --frames 120 --png .\out\peripheral_keyboard.png

Select a matrix row and the low bit of col, then return raw 4017 & 1E.
Use rows 0..8 for keys; row 9 is used by detection. No row-range validation is emitted.

EmitHelperStart("__fkb_read_row_col");
            EmitAsm("LDA", Imm(0x05));
            EmitAsm("STA", Mem(0x4016));
            EmitKeyboardDelayShort();
            // Establish row zero, then generate one high-to-low column edge
            // per requested advance. Repeated writes of 04 do not clock the counter.
            EmitAsm("LDA", Imm(0x04));
            EmitAsm("STA", Mem(0x4016));
            EmitKeyboardDelayLong();
            EmitAsm("LDX", Mem(CallArgBase));
            string selectedRow = NewGeneratedLabel("fkb_selected_row");
            EmitAsm("BEQ", Rel(selectedRow));
            string adv = NewGeneratedLabel("fkb_adv_row");
            _assembly.Add(Expr.Make(Tag.Label, adv));
            EmitAsm("LDA", Imm(0x06));
            EmitAsm("STA", Mem(0x4016));
            EmitKeyboardDelayLong();
            EmitAsm("LDA", Imm(0x04));
            EmitAsm("STA", Mem(0x4016));
            EmitKeyboardDelayLong();
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(adv));
            _assembly.Add(Expr.Make(Tag.Label, selectedRow));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("AND", Imm(1));
            string readNow = NewGeneratedLabel("fkb_read_now");
            EmitAsm("BEQ", Rel(readNow));
            EmitAsm("LDA", Imm(0x06));
            EmitAsm("STA", Mem(0x4016));
            EmitKeyboardDelayLong();
            _assembly.Add(Expr.Make(Tag.Label, readNow));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x1E));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

Balayez les neuf lignes et les deux groupes de colonnes dans un tampon de 18 octets afin d’examiner plusieurs touches à partir d’une même capture de la matrice.

Syntaxe

void __fkb_scan(u8* dst18);

Paramètres

dst18

Zone inscriptible d’au moins 18 octets. L’élément row*2+col reçoit la valeur brute du groupe correspondant. Aucun contrôle du pointeur nul ni de la longueur n’est effectué.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Ces API accèdent directement à $4016/$4017. N’entrelacez pas sur les mêmes ports des opérations de manette, clavier ou série pilotées par interruption. Les positions de décalage des contrôleurs peuvent aussi être affectées. L’exemple désactive la NMI pendant la capture des entrées, puis l’active à l’initialisation de l’affichage.

Les groupes de touches sont les bits bruts 1 à 4 : une touche enfoncée efface son bit, et un groupe au repos vaut 0x1E. Ce ne sont ni du texte ASCII ni un masque où un signifie enfoncé. Un appareil débranché peut aussi se lire à zéro ; vérifiez sa présence avant d’interpréter cela comme toutes les touches maintenues.

Écrit 5 dans $4016 pour revenir à la ligne 0, puis avance les lignes par transitions haut-bas du bit de sélection de colonne. Outre les instructions environnantes, le code généré inclut 12 cycles CPU de NOP après la réinitialisation et 50 après la sélection de colonne. Il écrit zéro à la sortie pour désactiver la matrice.

Une vérification de régression distincte examine les lignes 0 à 9, les deux colonnes, le balayage de neuf lignes, les délais de stabilisation et l’état final des ports à partir de traces de bus CPU exécutées. Elle n’injecte aucun signal de touche physique.

Lit la colonne 0 puis la colonne 1 de chaque ligne. Le balayage est séquentiel ; ce n’est pas un instantané simultané de toutes les touches. Un groupe à zéro n’interrompt pas le balayage.

Ces images exécutent les ROM téléchargeables sans modification dans KUROSAKI. Son bus d’entrée modélise les manettes, mais pas les signaux du clavier, du pistolet optique ou d’un adaptateur série. Les bits d’entrée externes se lisent à zéro ; les captures ne valident donc pas ces appareils. Les touches physiques, la détection optique et la communication restent non testées.

NESdev : clavier Family BASIC

Exemple d’utilisation

#include "fc_ports_scene.h"
void main(void){
    u8 row;
    __irq_disable();__ppu_ctrl_set(0);port_phase=1;
    port_result[0]=__fkb_detect();
    __fkb_scan(key_matrix);
    port_result[1]=__fkb_read_row_col(6,0);
    port_result[2]=0;
    if(port_result[0] && !(port_result[1]&16))port_result[2]=1;
    port_phase=2;port_result[31]=165;
    m_init();m_text(2,2,"KEYBOARD STARTUP SNAPSHOT");m_wait();
    m_text(2,4,"DEVICE DETECT");port_number(25,4,port_result[0]);m_wait();
    m_text(2,6,"ROW 6 COL 0");port_number(25,6,port_result[1]);m_wait();
    m_text(2,8,"A KEY - GUARDED");port_number(25,8,port_result[2]);m_wait();
    m_text(2,10,"ROW   COL0  COL1  (HEX)");m_wait();
    for(row=0;row<9;row++){
        m_put(3,12+row,'0'+row);port_hex(9,12+row,key_matrix[row*2]);port_hex(15,12+row,key_matrix[row*2+1]);m_wait();
    }
    m_text(2,23,"RAW MATRIX - NOT ASCII");m_wait();
    while(1){m_wait();}
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Dans cette exécution KUROSAKI, DEVICE DETECT, ROW 6 COL 0 et A KEY - GUARDED valent tous 000 ; les neuf paires COL0/COL1 valent 00. A se trouve ligne 6, colonne 0, bit 4, mais l’échec de détection empêche de signaler le zéro brut comme une touche enfoncée. Le tableau est une capture unique au démarrage.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\peripheral_keyboard.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\peripheral_keyboard.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm
.\kurosaki\kurosaki.exe run .\out\peripheral_keyboard.nes --frames 120 --png .\out\peripheral_keyboard.png

Write 18 raw masked samples (4017 & 1E), two per row, to caller storage; reset 4016 afterward.

EmitHelperStart("__fkb_scan");
            EmitAsm("LDA", Imm(0x05));
            EmitAsm("STA", Mem(0x4016));
            EmitKeyboardDelayShort();
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDX", Imm(9));
            string rowLoop = NewGeneratedLabel("fkb_scan_row");
            _assembly.Add(Expr.Make(Tag.Label, rowLoop));
            EmitAsm("LDA", Imm(0x04));
            EmitAsm("STA", Mem(0x4016));
            EmitKeyboardDelayLong();
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x1E));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INY");
            EmitAsm("LDA", Imm(0x06));
            EmitAsm("STA", Mem(0x4016));
            EmitKeyboardDelayLong();
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x1E));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INY");
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(rowLoop));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            EmitAsm("RTS");

Émet SEI pour positionner le bit I du registre d’état du processeur et masquer les requêtes IRQ ordinaires. Sert aux sections critiques vis-à-vis des IRQ. Ne désactive pas la NMI, ne coupe pas le son de l’APU, n’acquitte pas la source IRQ et ne sauvegarde pas le masque précédent.

Syntaxe

void __irq_disable(void);

Valeur renvoyée

Aucune (void).

Conditions et limites

Le bit I ne contrôle que les IRQ ordinaires : la NMI peut interrompre cette section. Masquer les IRQ n’acquitte aucune requête de périphérique et ne protège pas les données partagées avec la NMI. Préparez séparément sources et gestionnaires. L’exemple ne teste aucun périphérique générant des IRQ.

NESdev: NMI

NESdev : interruptions du CPU

Exemple d’utilisation

__irq_disable();
disabled=(__irq_save()&4)>>2; // The CPU I bit must be 1.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme distingue le masque IRQ du processeur du contrôle NMI de la PPU. En bleu sur fond noir doivent apparaître IRQ DISABLED I = 001, IRQ ENABLED I = 000, SAVED SECTION I = 001 et RESTORED I = 000. Chaque valeur représente le bit I extrait, pas l’octet d’état complet. FAILED CHECKS doit valoir 000.

Exécutez au moins 360 images pour terminer la démonstration des 256 attentes. NMI DELTA 3 WAITS doit valoir 003 même avec les IRQ masquées ; NMI DELTA 256 WAITS doit valoir 000, car le compteur sur un octet boucle. NMI OFF DELTA doit aussi valoir 000. Le programme utilise le gestionnaire par défaut sans runtime.c. Vingt et un contrôles d’état distincts couvrent notamment la restauration des indicateurs et des attentes observées sur une durée limitée avec NMI désactivée ou un gestionnaire personnalisé vide. KUROSAKI/NROM est vérifié, pas le matériel réel.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\interrupt_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\font.chr -o .\out\interrupt_intrinsics.nes --no-cache --no-disasm

Emit SEI to mask CPU IRQs; NMI is unaffected.

case "__irq_disable": if (!Need(0)) return true; EmitAsm("SEI"); return true;

Émet CLI pour effacer le bit I du registre d’état du processeur et autoriser le traitement des IRQ ordinaires. Ne configure aucune source d’interruption du mapper ou de l’APU. Préparez le gestionnaire et l’acquittement de la requête avant d’activer cette source.

Syntaxe

void __irq_enable(void);

Valeur renvoyée

Aucune (void).

Conditions et limites

Le bit I ne contrôle que les IRQ ordinaires : la NMI peut interrompre cette section. Masquer les IRQ n’acquitte aucune requête de périphérique et ne protège pas les données partagées avec la NMI. Préparez séparément sources et gestionnaires. L’exemple ne teste aucun périphérique générant des IRQ.

NESdev: NMI

NESdev : interruptions du CPU

Exemple d’utilisation

__irq_enable();
enabled=(__irq_save()&4)>>2; // Save returns the old I bit: 0, then masks IRQ.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme distingue le masque IRQ du processeur du contrôle NMI de la PPU. En bleu sur fond noir doivent apparaître IRQ DISABLED I = 001, IRQ ENABLED I = 000, SAVED SECTION I = 001 et RESTORED I = 000. Chaque valeur représente le bit I extrait, pas l’octet d’état complet. FAILED CHECKS doit valoir 000.

Exécutez au moins 360 images pour terminer la démonstration des 256 attentes. NMI DELTA 3 WAITS doit valoir 003 même avec les IRQ masquées ; NMI DELTA 256 WAITS doit valoir 000, car le compteur sur un octet boucle. NMI OFF DELTA doit aussi valoir 000. Le programme utilise le gestionnaire par défaut sans runtime.c. Vingt et un contrôles d’état distincts couvrent notamment la restauration des indicateurs et des attentes observées sur une durée limitée avec NMI désactivée ou un gestionnaire personnalisé vide. KUROSAKI/NROM est vérifié, pas le matériel réel.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\interrupt_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\font.chr -o .\out\interrupt_intrinsics.nes --no-cache --no-disasm

Emit CLI to unmask CPU IRQs; the caller must have a valid interrupt handler.

case "__irq_enable": if (!Need(0)) return true; EmitAsm("CLI"); return true;
                // Return the saved processor status in A after masking IRQs; restore consumes a status byte, not a Boolean.

Évalue l’octet d’état fourni, l’empile avec PHA et restaure l’état du processeur avec PLP. Rétablit le masque IRQ et les indicateurs arithmétiques sauvegardés, sans autoriser systématiquement les IRQ. Les expressions C exécutées ensuite peuvent modifier à nouveau les indicateurs arithmétiques.

Syntaxe

void __irq_restore(u8 state);

Paramètres

state

L’état complet du processeur sur 8 bits, capturé par __irq_save. Conservez-le pour __irq_restore sans le convertir en booléen. Le bit 2 est I : 1 masque les IRQ, 0 les autorise. La représentation empilée par PHP positionne les bits 4 et 5.

Valeur renvoyée

Aucune (void).

Conditions et limites

Le bit I ne contrôle que les IRQ ordinaires : la NMI peut interrompre cette section. Masquer les IRQ n’acquitte aucune requête de périphérique et ne protège pas les données partagées avec la NMI. Préparez séparément sources et gestionnaires. L’exemple ne teste aucun périphérique générant des IRQ.

NESdev: NMI

NESdev : interruptions du CPU

Exemple d’utilisation

__irq_restore(saved_state); // Restore the caller's original IRQ mask.
restored=(__irq_save()&4)>>2; // Original I was 0; this probe masks it again.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme distingue le masque IRQ du processeur du contrôle NMI de la PPU. En bleu sur fond noir doivent apparaître IRQ DISABLED I = 001, IRQ ENABLED I = 000, SAVED SECTION I = 001 et RESTORED I = 000. Chaque valeur représente le bit I extrait, pas l’octet d’état complet. FAILED CHECKS doit valoir 000.

Exécutez au moins 360 images pour terminer la démonstration des 256 attentes. NMI DELTA 3 WAITS doit valoir 003 même avec les IRQ masquées ; NMI DELTA 256 WAITS doit valoir 000, car le compteur sur un octet boucle. NMI OFF DELTA doit aussi valoir 000. Le programme utilise le gestionnaire par défaut sans runtime.c. Vingt et un contrôles d’état distincts couvrent notamment la restauration des indicateurs et des attentes observées sur une durée limitée avec NMI désactivée ou un gestionnaire personnalisé vide. KUROSAKI/NROM est vérifié, pas le matériel réel.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\interrupt_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\font.chr -o .\out\interrupt_intrinsics.nes --no-cache --no-disasm

Restore processor status with PLP, including arithmetic flags and the saved IRQ mask.

case "__irq_restore": if (!Need(1)) return true; Load1(args[0]); EmitAsm("PHA"); EmitAsm("PLP"); return true;

Sauvegarde l’octet d’état du processeur avec PHP, masque les IRQ avec SEI, puis renvoie l’octet sauvegardé via PLA. Le bit I sauvegardé indique l’état avant le masquage. Associez cet appel à __irq_restore pour qu’une section critique imbriquée conserve un masquage IRQ déjà actif.

Syntaxe

u8 __irq_save(void);

Valeur renvoyée

L’état complet du processeur sur 8 bits, capturé par __irq_save. Conservez-le pour __irq_restore sans le convertir en booléen. Le bit 2 est I : 1 masque les IRQ, 0 les autorise. La représentation empilée par PHP positionne les bits 4 et 5.

Conditions et limites

Le bit I ne contrôle que les IRQ ordinaires : la NMI peut interrompre cette section. Masquer les IRQ n’acquitte aucune requête de périphérique et ne protège pas les données partagées avec la NMI. Préparez séparément sources et gestionnaires. L’exemple ne teste aucun périphérique générant des IRQ.

NESdev: NMI

NESdev : interruptions du CPU

Exemple d’utilisation

saved_state=__irq_save(); // Save all processor-status bits, then set I.
inside=(__irq_save()&4)>>2; // IRQ remains masked inside this section.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme distingue le masque IRQ du processeur du contrôle NMI de la PPU. En bleu sur fond noir doivent apparaître IRQ DISABLED I = 001, IRQ ENABLED I = 000, SAVED SECTION I = 001 et RESTORED I = 000. Chaque valeur représente le bit I extrait, pas l’octet d’état complet. FAILED CHECKS doit valoir 000.

Exécutez au moins 360 images pour terminer la démonstration des 256 attentes. NMI DELTA 3 WAITS doit valoir 003 même avec les IRQ masquées ; NMI DELTA 256 WAITS doit valoir 000, car le compteur sur un octet boucle. NMI OFF DELTA doit aussi valoir 000. Le programme utilise le gestionnaire par défaut sans runtime.c. Vingt et un contrôles d’état distincts couvrent notamment la restauration des indicateurs et des attentes observées sur une durée limitée avec NMI désactivée ou un gestionnaire personnalisé vide. KUROSAKI/NROM est vérifié, pas le matériel réel.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\interrupt_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\font.chr -o .\out\interrupt_intrinsics.nes --no-cache --no-disasm

Return the processor-status byte captured before SEI. Pass that byte to __irq_restore.

case "__irq_save": if (!Need(0)) return true; EmitAsm("PHP"); EmitAsm("SEI"); EmitAsm("PLA"); return true;

Alias de l’opération MMC3 de verrouillage/rechargement de __mapper_irq_set. Le mot scanline ne garantit pas une ligne d’écran absolue.

Syntaxe

void __irq_scanline_set(u8 line);

Paramètres

line

Valeur de verrouillage du compteur sur huit bits, de 0 à 255, et non une coordonnée Y absolue. Le moment du rechargement et les transitions PPU A12 admissibles déterminent le déclenchement. Zéro est valide et ne signifie pas « désactiver les interruptions ».

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

MMC3 uniquement. Fournissez un gestionnaire __nes_irq, des transitions PPU A12 admissibles, l’activation IRQ du mapper et __irq_enable() côté CPU. L’exemple active le rendu avec les motifs de fond à $0000 et les sprites à $1000. Cette leçon ne vérifie pas la synchronisation sur une ligne exacte du matériel réel.

L’acquittement et la désactivation MMC3 écrivent tous deux dans $E000. Cela efface la demande actuelle et désactive les suivantes. Rappelez __mapper_irq_enable() au moment voulu pour armer une autre interruption. Aucune de ces opérations ne modifie le masque d’interruptions CPU ni l’activation NMI.

Le compilateur émet RTI pour un gestionnaire d’interruption personnalisé, mais celui-ci doit préserver les registres A/X/Y et les zones temporaires partagées qu’il modifie. L’exemple sauvegarde A/X/Y et n’utilise qu’un incrément d’octet et un acquittement sans argument. Si vous ajoutez des appels C, examinez aussi leur stockage partagé.

Exemple d’utilisation

irq_phase=2;
    __irq_scanline_set(7); __mapper_irq_enable();
    for (i=0;i<6;i++) { m_wait(); }
    mapper_result[17]=irq_count;

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple MMC3 affiche les marqueurs CHR 19/20, 21/22 et 23/24. Les lectures CIRAM donnent A B A B en mirroring vertical et A A B B en horizontal. Les comptes IRQ sont 01→02→03→03 : chacune des trois premières activations explicites autorise une interruption ; le compteur reste fixe après désactivation. Chaque étape attend six images.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_controls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_controls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Write the MMC3 IRQ latch and reload registers. This does not enable IRQ delivery.

__joypad2p_voice est un autre nom d’entrée de la routine __mic_read2p. Les deux lisent le même bit numérique du microphone. « Voice » n’implique aucun traitement audio : chaque appel prend un échantillon distinct, qui peut différer si le signal change entre les appels.

Lit le signal numérique du microphone de la seconde manette Famicom dans le bit 2 de $4016. La routine lit le registre une fois, applique le masque 0x04 et normalise à 0 ou 1 sans inversion. Elle ne verrouille pas les états des manettes, n’enregistre pas de son, ne mesure pas le volume et ne reconnaît pas la parole.

Syntaxe

u8 __joypad2p_voice(void);

Valeur renvoyée

Exactement 1 si $4016 & 0x04 est non nul, sinon 0. Il s’agit du niveau numérique échantillonné, pas d’un masque de boutons, d’une amplitude, d’une fréquence ou d’un nombre de mots prononcés.

Conditions et limites

Bien que le microphone appartienne à la manette 2, cette routine accède à $4016, pas à $4017. Une lecture du registre peut aussi faire avancer le flux série de la manette lorsque le strobe est bas ; n’insérez donc pas de lecture du microphone dans une autre boucle de lecture de huit bits. Aucun historique d’entrée mémorisé n’est mis à jour.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Exemple d’utilisation

voice=__joypad2p_voice();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare l’entrée ordinaire D0, l’extension D1 et le niveau numérique du microphone. Maintenez A sur la manette 1 et B sur la manette 2 jusqu’à la capture. NORMAL P1 et NORMAL P2 affichent 001 et 002. Dans l’exécution KUROSAKI fournie, D1 PORT 1, D1 PORT 2, EXP ALIAS 1, EXP ALIAS 2, MIC LEVEL et MIC DIRECT affichent 000, car ces lignes ne sont pas émulées. Les valeurs restent ensuite fixes. Avec des périphériques adaptés et leurs lignes implémentées, les valeurs dépendent des entrées réelles ; interprétez-les selon les bits décrits ci-dessus au lieu d’attendre ces zéros.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\expansion_input.c -I .\kitaq-docs\samples -I .\kitaqfc\lib -o .\out\expansion_input.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Return controller-port 4016 bit 2 normalized to 0 or 1; this is a microphone level bit, not PCM audio.

Calcule une multiplication-accumulation non signée.

Syntaxe

u16 __mac16(u16 acc, u16 a, u8 b);

Paramètres

acc

Accumulateur sur 16 bits à ajouter.

a

Mot non signé de 0 à 65535.

b

Coefficient non signé de 0 à 255.

Valeur renvoyée

Renvoie les 16 bits de poids faible de acc+a*b.

Conditions et limites

Sur FC, les fonctions nommées q8_8/q1_7 utilisent les produits entiers bruts, sans décalage de mise à l’échelle fixe. Les fonctions Q1.7 sont des alias des opérations signées correspondantes. L’appelant gère les unités ; les résultats signés sont renvoyés comme motifs de bits u16.

Exemple d’utilisation

// Compare literal coefficients with values read from RAM.
result[8]=__mac16(65500,513,127);
v0=65500;v1=513;v2=127;
result[9]=__mac16(v0,v1,v2);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Comparez les entrées littérales aux valeurs en RAM. Les résultats représentatifs sont affichés sur 16 bits non signés ; les négatifs utilisent le complément à deux. Le GB remet à l’échelle les produits à virgule fixe, tandis que le FC renvoie des produits entiers : des entrées identiques ne donnent donc pas nécessairement les mêmes résultats.

L’extrait stocke les valeurs suivantes sur 16 bits : result[8]=65115, result[9]=65115. Chaque calcul avec une entrée littérale correspond à son équivalent avec une entrée en RAM. L’écran affiche des valeurs représentatives ; le tableau result conserve tous les résultats.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch3_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return acc+a*b modulo 65536 using unsigned multiplication.

case "__mac16": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,2,1}, funcName);

void EmitHelperMath()
        {
            // Consume eight multiplier bits and accumulate the low product word in shared temporaries, returning A/X.
            EmitHelperStart("__mul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDX", Imm(8));
            string loop = NewGeneratedLabel("mul16x8_loop");
            string skip = NewGeneratedLabel("mul16x8_skip_add");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LSR", Mem(CallArgBase + 2));
            EmitAsm("BCC", Rel(skip));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("ADC", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, skip));
            EmitAsm("ASL", Mem(CallArgBase));
            EmitAsm("ROL", Mem(CallArgBase + 1));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(loop));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            // Zero-extend the byte multiplicand, reuse word multiplication and return its high byte.
            EmitHelperStart("__mul8x8_hi");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("TXA");
            EmitAsm("RTS");

            // Convert signed operands to magnitudes, multiply, then restore the product sign modulo 65536.
            EmitHelperStart("__smul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            string aPos = NewGeneratedLabel("smul_a_positive");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(aPos));
            EmitAsm("LDA", Mem(CallArgBase)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("LDA", Mem(CallArgBase + 1)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, aPos));
            string bPos = NewGeneratedLabel("smul_b_positive");
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(bPos));
            EmitAsm("LDA", Mem(CallArgBase + 2)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, bPos));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STX", Mem(_runtimeIntrinsicTmp1Address));
            string sdone = NewGeneratedLabel("smul_done");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("BEQ", Rel(sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            EmitMacHelper("__mac16", "__mul16x8");
            EmitMacHelper("__smac16", "__smul16x8");
            EmitDot2Helper("__dot2_q8_8", "__mul16x8");
            EmitDot3Helper("__dot3_q8_8", "__mul16x8");
            EmitDot2Helper("__sdot2_q8_8", "__smul16x8");
            EmitDot3Helper("__sdot3_q8_8", "__smul16x8");
        }

Additionne les différences absolues en X et en Y entre deux points.

Syntaxe

u8 __manhattan(u8 x1, u8 y1, u8 x2, u8 y2);

Paramètres

x1

Coordonnée X du premier point, de 0 à 255.

y1

Coordonnée Y du premier point, de 0 à 255.

x2

Coordonnée X du second point, de 0 à 255.

y2

Coordonnée Y du second point, de 0 à 255.

Valeur renvoyée

Renvoie l’octet de poids faible de |x1−x2|+|y1−y2| ; les distances supérieures à 255 rebouclent.

Exemple d’utilisation

result[5]=__manhattan(2,3,9,11);result[6]=__manhattan(0,0,255,255);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Testez intérieur, limites, point extérieur et largeur nulle : INSIDE=1, RIGHT EDGE=0, LEFT EDGE=0, HIGH X=1. Vérifiez la distance 15, la distance rebouclée 254 et les indices de tableau 64/65280.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch3_coordinates.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_coordinates.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return abs(x1-x2)+abs(y1-y2) modulo 256; large distances are not saturated.

case "__manhattan":
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1,1}, "__manhattan");

void EmitHelperGeometryAndRng()
        {
            EmitHelperStart("__xy_in_rect");
            string xyFalse = NewGeneratedLabel("xy_in_rect_false");
            string xyDone = NewGeneratedLabel("xy_in_rect_done");
            // return (x-rx < rw) && (y-ry < rh), using unsigned subtract to avoid rx+rw overflow.
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("SEC");
            EmitAsm("SBC", Mem(CallArgBase + 2));
            EmitAsm("BCC", Rel(xyFalse));
            EmitAsm("CMP", Mem(CallArgBase + 4));
            EmitAsm("BCS", Rel(xyFalse));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("SEC");
            EmitAsm("SBC", Mem(CallArgBase + 3));
            EmitAsm("BCC", Rel(xyFalse));
            EmitAsm("CMP", Mem(CallArgBase + 5));
            EmitAsm("BCS", Rel(xyFalse));
            EmitAsm("LDA", Imm(1));
            EmitAsm("JMP", Abs(xyDone));
            _assembly.Add(Expr.Make(Tag.Label, xyFalse));
            EmitAsm("LDA", Imm(0));
            _assembly.Add(Expr.Make(Tag.Label, xyDone));
            EmitAsm("RTS");

            EmitHelperStart("__manhattan");
            // dx = abs(x1-x2)
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("SEC");
            EmitAsm("SBC", Mem(CallArgBase + 2));
            string mdxOk = NewGeneratedLabel("manhattan_dx_ok");
            EmitAsm("BCS", Rel(mdxOk));
            EmitAsm("EOR", Imm(0xFF));
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(1));
            _assembly.Add(Expr.Make(Tag.Label, mdxOk));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            // dy = abs(y1-y2), then add dx.
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("SEC");
            EmitAsm("SBC", Mem(CallArgBase + 3));
            string mdyOk = NewGeneratedLabel("manhattan_dy_ok");
            EmitAsm("BCS", Rel(mdyOk));
            EmitAsm("EOR", Imm(0xFF));
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(1));
            _assembly.Add(Expr.Make(Tag.Label, mdyOk));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Save X-coordinate separately while multiplying width by Y, then add X with carry into the high byte.
            EmitHelperStart("__map_index");
            // args: x, y, width. Return y * width + x as u16.
            EmitAsm("LDA", Mem(CallArgBase));      // x
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Mem(CallArgBase + 1));  // y
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(CallArgBase + 2));  // width as u16 multiplicand
            EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("TXA");
            EmitAsm("ADC", Imm(0));
            EmitAsm("TAX");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Replace both bytes of the persistent generator state with the supplied seed.
            EmitHelperStart("__rng_seed");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeRngLoAddress));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeRngHiAddress));
            EmitAsm("RTS");

            EmitHelperStart("__rng8");
            // 16-bit Galois LFSR: if low bit set, shift right then xor $B400.
            EmitAsm("LDA", Mem(_runtimeRngLoAddress));
            EmitAsm("ORA", Mem(_runtimeRngHiAddress));
            // Replace the all-zero LFSR state with a deterministic nonzero seed before advancing.
            string seeded = NewGeneratedLabel("rng_seeded");
            EmitAsm("BNE", Rel(seeded));
            EmitAsm("LDA", Imm(0x5A));
            EmitAsm("STA", Mem(_runtimeRngLoAddress));
            EmitAsm("LDA", Imm(0xA5));
            EmitAsm("STA", Mem(_runtimeRngHiAddress));
            _assembly.Add(Expr.Make(Tag.Label, seeded));
            EmitAsm("LDA", Mem(_runtimeRngLoAddress));
            EmitAsm("AND", Imm(1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LSR", Mem(_runtimeRngHiAddress));
            EmitAsm("ROR", Mem(_runtimeRngLoAddress));
            string rngNoXor = NewGeneratedLabel("rng_no_xor");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("BEQ", Rel(rngNoXor));
            EmitAsm("LDA", Mem(_runtimeRngHiAddress));
            EmitAsm("EOR", Imm(0xB4));
            EmitAsm("STA", Mem(_runtimeRngHiAddress));
            _assembly.Add(Expr.Make(Tag.Label, rngNoXor));
            EmitAsm("LDA", Mem(_runtimeRngLoAddress));
            EmitAsm("EOR", Mem(_runtimeRngHiAddress));
            EmitAsm("RTS");
        }

Convertit les coordonnées d’une case en indice de tableau rangé par lignes.

Syntaxe

u16 __map_index(u8 x, u8 y, u8 width);

Paramètres

x

Colonne de 0 à 255, normalement inférieure à width.

y

Ligne de 0 à 255.

width

Nombre de cases par ligne, de 0 à 255.

Valeur renvoyée

Renvoie y*width+x sous forme de u16 ; ne valide pas les coordonnées.

Exemple d’utilisation

result[7]=__map_index(4,3,20);result[8]=__map_index(255,255,255);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Testez intérieur, limites, point extérieur et largeur nulle : INSIDE=1, RIGHT EDGE=0, LEFT EDGE=0, HIGH X=1. Vérifiez la distance 15, la distance rebouclée 254 et les indices de tableau 64/65280.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch3_coordinates.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_coordinates.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return y*width+x as a word without checking coordinates against map dimensions.

case "__map_index":
                    if (TryEmitMapIndexInline(args, ctx)) return true;
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1}, "__map_index");

void EmitHelperGeometryAndRng()
        {
            EmitHelperStart("__xy_in_rect");
            string xyFalse = NewGeneratedLabel("xy_in_rect_false");
            string xyDone = NewGeneratedLabel("xy_in_rect_done");
            // return (x-rx < rw) && (y-ry < rh), using unsigned subtract to avoid rx+rw overflow.
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("SEC");
            EmitAsm("SBC", Mem(CallArgBase + 2));
            EmitAsm("BCC", Rel(xyFalse));
            EmitAsm("CMP", Mem(CallArgBase + 4));
            EmitAsm("BCS", Rel(xyFalse));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("SEC");
            EmitAsm("SBC", Mem(CallArgBase + 3));
            EmitAsm("BCC", Rel(xyFalse));
            EmitAsm("CMP", Mem(CallArgBase + 5));
            EmitAsm("BCS", Rel(xyFalse));
            EmitAsm("LDA", Imm(1));
            EmitAsm("JMP", Abs(xyDone));
            _assembly.Add(Expr.Make(Tag.Label, xyFalse));
            EmitAsm("LDA", Imm(0));
            _assembly.Add(Expr.Make(Tag.Label, xyDone));
            EmitAsm("RTS");

            EmitHelperStart("__manhattan");
            // dx = abs(x1-x2)
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("SEC");
            EmitAsm("SBC", Mem(CallArgBase + 2));
            string mdxOk = NewGeneratedLabel("manhattan_dx_ok");
            EmitAsm("BCS", Rel(mdxOk));
            EmitAsm("EOR", Imm(0xFF));
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(1));
            _assembly.Add(Expr.Make(Tag.Label, mdxOk));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            // dy = abs(y1-y2), then add dx.
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("SEC");
            EmitAsm("SBC", Mem(CallArgBase + 3));
            string mdyOk = NewGeneratedLabel("manhattan_dy_ok");
            EmitAsm("BCS", Rel(mdyOk));
            EmitAsm("EOR", Imm(0xFF));
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(1));
            _assembly.Add(Expr.Make(Tag.Label, mdyOk));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Save X-coordinate separately while multiplying width by Y, then add X with carry into the high byte.
            EmitHelperStart("__map_index");
            // args: x, y, width. Return y * width + x as u16.
            EmitAsm("LDA", Mem(CallArgBase));      // x
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Mem(CallArgBase + 1));  // y
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(CallArgBase + 2));  // width as u16 multiplicand
            EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("TXA");
            EmitAsm("ADC", Imm(0));
            EmitAsm("TAX");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Replace both bytes of the persistent generator state with the supplied seed.
            EmitHelperStart("__rng_seed");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeRngLoAddress));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeRngHiAddress));
            EmitAsm("RTS");

            EmitHelperStart("__rng8");
            // 16-bit Galois LFSR: if low bit set, shift right then xor $B400.
            EmitAsm("LDA", Mem(_runtimeRngLoAddress));
            EmitAsm("ORA", Mem(_runtimeRngHiAddress));
            // Replace the all-zero LFSR state with a deterministic nonzero seed before advancing.
            string seeded = NewGeneratedLabel("rng_seeded");
            EmitAsm("BNE", Rel(seeded));
            EmitAsm("LDA", Imm(0x5A));
            EmitAsm("STA", Mem(_runtimeRngLoAddress));
            EmitAsm("LDA", Imm(0xA5));
            EmitAsm("STA", Mem(_runtimeRngHiAddress));
            _assembly.Add(Expr.Make(Tag.Label, seeded));
            EmitAsm("LDA", Mem(_runtimeRngLoAddress));
            EmitAsm("AND", Imm(1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LSR", Mem(_runtimeRngHiAddress));
            EmitAsm("ROR", Mem(_runtimeRngLoAddress));
            string rngNoXor = NewGeneratedLabel("rng_no_xor");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("BEQ", Rel(rngNoXor));
            EmitAsm("LDA", Mem(_runtimeRngHiAddress));
            EmitAsm("EOR", Imm(0xB4));
            EmitAsm("STA", Mem(_runtimeRngHiAddress));
            _assembly.Add(Expr.Make(Tag.Label, rngNoXor));
            EmitAsm("LDA", Mem(_runtimeRngLoAddress));
            EmitAsm("EOR", Mem(_runtimeRngHiAddress));
            EmitAsm("RTS");
        }

Renvoie le numéro de mapper choisi à la compilation, pour l’initialisation ou l’affichage propres à la carte.

Syntaxe

u8 __mapper_id(void);

Valeur renvoyée

Numéro de mapper sur huit bits : NROM=0, MMC1=1, UxROM=2, CNROM=3, MMC3=4, MMC5=5, AxROM=7, VRC6=24, FME7=69 et VRC7=85. Le compilateur émet une constante ; il n’interroge pas le matériel en fonctionnement.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

Exemple d’utilisation

mapper_result[0] = __mapper_id();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple MMC3 affiche les marqueurs CHR 19/20, 21/22 et 23/24. Les lectures CIRAM donnent A B A B en mirroring vertical et A A B B en horizontal. Les comptes IRQ sont 01→02→03→03 : chacune des trois premières activations explicites autorise une interruption ; le compteur reste fixe après désactivation. Chaque étape attend six images.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_controls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_controls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Mapper
Return the low byte of the mapper number selected for this build; no cartridge probe is performed.

Acquitte MMC3 dans le gestionnaire IRQ. Comme l’opération écrit dans $E000, elle désactive aussi les demandes IRQ suivantes.

Syntaxe

void __mapper_irq_ack(void);

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

MMC3 uniquement. Fournissez un gestionnaire __nes_irq, des transitions PPU A12 admissibles, l’activation IRQ du mapper et __irq_enable() côté CPU. L’exemple active le rendu avec les motifs de fond à $0000 et les sprites à $1000. Cette leçon ne vérifie pas la synchronisation sur une ligne exacte du matériel réel.

L’acquittement et la désactivation MMC3 écrivent tous deux dans $E000. Cela efface la demande actuelle et désactive les suivantes. Rappelez __mapper_irq_enable() au moment voulu pour armer une autre interruption. Aucune de ces opérations ne modifie le masque d’interruptions CPU ni l’activation NMI.

Le compilateur émet RTI pour un gestionnaire d’interruption personnalisé, mais celui-ci doit préserver les registres A/X/Y et les zones temporaires partagées qu’il modifie. L’exemple sauvegarde A/X/Y et n’utilise qu’un incrément d’octet et un acquittement sans argument. Si vous ajoutez des appels C, examinez aussi leur stockage partagé.

Exemple d’utilisation

void __nes_irq(void) {
    __asm {
        PHA
        TXA
        PHA
        TYA
        PHA
    }
    irq_count++;
    if (irq_phase == 1) { nes_mapper_irq_ack(); }
    else { __mapper_irq_ack(); }
    __asm {
        PLA
        TAY
        PLA
        TAX
        PLA
    }
}

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple MMC3 affiche les marqueurs CHR 19/20, 21/22 et 23/24. Les lectures CIRAM donnent A B A B en mirroring vertical et A A B B en horizontal. Les comptes IRQ sont 01→02→03→03 : chacune des trois premières activations explicites autorise une interruption ; le compteur reste fixe après désactivation. Chaque étape attend six images.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_controls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_controls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Use the same E000 write as disable; explicitly re-enable when another interrupt is needed.

Écrit dans $E000 pour effacer la demande IRQ MMC3 et désactiver les suivantes.

Syntaxe

void __mapper_irq_disable(void);

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

MMC3 uniquement. Fournissez un gestionnaire __nes_irq, des transitions PPU A12 admissibles, l’activation IRQ du mapper et __irq_enable() côté CPU. L’exemple active le rendu avec les motifs de fond à $0000 et les sprites à $1000. Cette leçon ne vérifie pas la synchronisation sur une ligne exacte du matériel réel.

L’acquittement et la désactivation MMC3 écrivent tous deux dans $E000. Cela efface la demande actuelle et désactive les suivantes. Rappelez __mapper_irq_enable() au moment voulu pour armer une autre interruption. Aucune de ces opérations ne modifie le masque d’interruptions CPU ni l’activation NMI.

Le compilateur émet RTI pour un gestionnaire d’interruption personnalisé, mais celui-ci doit préserver les registres A/X/Y et les zones temporaires partagées qu’il modifie. L’exemple sauvegarde A/X/Y et n’utilise qu’un incrément d’octet et un acquittement sans argument. Si vous ajoutez des appels C, examinez aussi leur stockage partagé.

Exemple d’utilisation

__irq_disable(); __mapper_irq_disable();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple MMC3 affiche les marqueurs CHR 19/20, 21/22 et 23/24. Les lectures CIRAM donnent A B A B en mirroring vertical et A A B B en horizontal. Les comptes IRQ sont 01→02→03→03 : chacune des trois premières activations explicites autorise une interruption ; le compteur reste fixe après désactivation. Chaque étape attend six images.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_controls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_controls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Write MMC3 E000 to disable and acknowledge mapper IRQs.

Écrit dans $E001 pour permettre à MMC3 de déclencher une IRQ lorsque la condition du compteur est remplie. Ne règle ni le verrou ni une demande de rechargement.

Syntaxe

void __mapper_irq_enable(void);

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

MMC3 uniquement. Fournissez un gestionnaire __nes_irq, des transitions PPU A12 admissibles, l’activation IRQ du mapper et __irq_enable() côté CPU. L’exemple active le rendu avec les motifs de fond à $0000 et les sprites à $1000. Cette leçon ne vérifie pas la synchronisation sur une ligne exacte du matériel réel.

L’acquittement et la désactivation MMC3 écrivent tous deux dans $E000. Cela efface la demande actuelle et désactive les suivantes. Rappelez __mapper_irq_enable() au moment voulu pour armer une autre interruption. Aucune de ces opérations ne modifie le masque d’interruptions CPU ni l’activation NMI.

Le compilateur émet RTI pour un gestionnaire d’interruption personnalisé, mais celui-ci doit préserver les registres A/X/Y et les zones temporaires partagées qu’il modifie. L’exemple sauvegarde A/X/Y et n’utilise qu’un incrément d’octet et un acquittement sans argument. Si vous ajoutez des appels C, examinez aussi leur stockage partagé.

Exemple d’utilisation

__mapper_irq_set(37); __mapper_irq_enable(); __irq_enable();
    for (i=0;i<6;i++) { m_wait(); }
    mapper_result[15]=irq_count;

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple MMC3 affiche les marqueurs CHR 19/20, 21/22 et 23/24. Les lectures CIRAM donnent A B A B en mirroring vertical et A A B B en horizontal. Les comptes IRQ sont 01→02→03→03 : chacune des trois premières activations explicites autorise une interruption ; le compteur reste fixe après désactivation. Chaque étape attend six images.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_controls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_controls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Write MMC3 E001. The CPU IRQ mask and a valid handler are separate caller responsibilities.

Écrit le verrou IRQ MMC3 à $C000 et demande son prochain rechargement à $C001. L’activation des interruptions est une opération distincte.

Syntaxe

void __mapper_irq_set(u8 scanline);

Paramètres

scanline

Valeur de verrouillage du compteur sur huit bits, de 0 à 255, et non une coordonnée Y absolue. Le moment du rechargement et les transitions PPU A12 admissibles déterminent le déclenchement. Zéro est valide et ne signifie pas « désactiver les interruptions ».

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

MMC3 uniquement. Fournissez un gestionnaire __nes_irq, des transitions PPU A12 admissibles, l’activation IRQ du mapper et __irq_enable() côté CPU. L’exemple active le rendu avec les motifs de fond à $0000 et les sprites à $1000. Cette leçon ne vérifie pas la synchronisation sur une ligne exacte du matériel réel.

L’acquittement et la désactivation MMC3 écrivent tous deux dans $E000. Cela efface la demande actuelle et désactive les suivantes. Rappelez __mapper_irq_enable() au moment voulu pour armer une autre interruption. Aucune de ces opérations ne modifie le masque d’interruptions CPU ni l’activation NMI.

Le compilateur émet RTI pour un gestionnaire d’interruption personnalisé, mais celui-ci doit préserver les registres A/X/Y et les zones temporaires partagées qu’il modifie. L’exemple sauvegarde A/X/Y et n’utilise qu’un incrément d’octet et un acquittement sans argument. Si vous ajoutez des appels C, examinez aussi leur stockage partagé.

Exemple d’utilisation

__mapper_irq_set(37); __mapper_irq_enable(); __irq_enable();
    for (i=0;i<6;i++) { m_wait(); }
    mapper_result[15]=irq_count;

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple MMC3 affiche les marqueurs CHR 19/20, 21/22 et 23/24. Les lectures CIRAM donnent A B A B en mirroring vertical et A A B B en horizontal. Les comptes IRQ sont 01→02→03→03 : chacune des trois premières activations explicites autorise une interruption ; le compteur reste fixe après désactivation. Chaque étape attend six images.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_controls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_controls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\mapper_banks.chr --no-cache --no-disasm

Alias the MMC3 IRQ latch/reload operation; other mapper profiles are rejected.

Copie de src vers dst le nombre d’octets indiqué. Le compteur sur 16 bits permet de dépasser 255 octets, par exemple pour copier une table entière en RAM. La lecture et l’écriture suivent l’ordre croissant des adresses.

Syntaxe

void __memcpy(u8* dst, const u8* src, u16 len);

Paramètres

dst

Pointeur vers le premier octet accessible en écriture de la destination. Prévoyez une zone contiguë assez grande pour toute l’opération ; aucun tampon n’est alloué automatiquement.

src

Pointeur vers le premier octet lisible de la source. Toute la zone doit rester accessible et inchangée pendant la copie.

len

Nombre d’octets en u16 (0–65535), et non nombre d’éléments. Le maximum du type ne garantit pas que la machine dispose d’un tampon valide de cette taille. Toute la zone doit tenir dans le mappage mémoire sélectionné.

Valeur renvoyée

Aucune (void).

Conditions et limites

Un compteur nul ne transfère aucun octet. Les effets de bord des expressions passées en argument ont néanmoins lieu : l’exemple fournit deux fonctions renvoyant des pointeurs et constate leurs deux appels malgré une longueur nulle.

Utilisez des zones source et destination sans chevauchement. Ces routines copient vers les adresses croissantes et n’offrent pas la sécurité de memmove en cas de recouvrement ; écraser une partie de la source encore non lue peut altérer la suite de la copie.

L’opération se termine avant de rendre la main. Elle ne change pas de banque ROM/RAM et ne limite pas automatiquement la zone aux bornes d’un tampon. Maintenez le mappage stable, utilisez des zones valides et coordonnez l’accès avec les interruptions utilisant les mêmes tampons.

Sur FC, dst est une adresse CPU, pas une adresse PPU. Une copie en RAM CPU ne modifie ni CHR, ni les tables de noms, ni les palettes ; leur chargement nécessite les API PPU/VRAM. Les routines auxiliaires générées partagent les arguments et les temporaires : ne les rappelez pas depuis une NMI/IRQ pendant une opération en cours.

Exemple d’utilisation

memory_reset();
__memcpy(memory_destination+1,memory_source+1,257);
memory_copy_word=memory_check(257,0); // 257 copied bytes; guards unchanged.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet exemple utilise __memcpy pour copier 257 octets suivant un motif connu à partir du décalage 1. memory_check compare les tableaux source et destination en entier ; la ligne COPY WORD doit afficher 257. Le premier octet sert de garde et les octets suivant le bloc doivent également rester inchangés.

Le programme complet initialise deux tampons de 264 octets avant chaque opération, puis vérifie tous les octets de la source, de la destination et des zones de garde. L’écran attendu affiche COPY WORD 257, FILL WORD 257, COPY BYTE 255, FILL BYTE 255, COPY16 016, COPY32 032, ZERO CALLS 002 et FAILED 000. WORD/BYTE désignent la largeur du compteur, pas la taille des éléments copiés. Ces nombres proviennent des vérifications de l’exemple ; ces fonctions void ne renvoient aucune valeur.

Les captures montrent du texte noir sur blanc sur DMG, bleu sur blanc sur CGB et bleu sur noir sur FC. L’exemple vérifie des opérations en RAM ; le texte en présente les résultats, sans illustrer une primitive de dessin. Des contrôles distincts sur émulateur couvrent 88 cas par plateforme : longueurs constantes ou déterminées à l’exécution de 0, 1, 16, 17, 32, 33, 64, 65 et 255 octets, plus 256 et 257 pour les compteurs sur 16 bits. Aucun test sur matériel réel n’a été effectué.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\memory_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\memory_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

memory / bit / math
Copy len bytes forward between readable/writable CPU ranges; overlapping copies are not memmove.
Zero length performs no memory transfer; argument side effects are evaluated before expansion.

case "__memcpy":
                    if (TryEmitMemcpyOrMemsetInline(funcName, args, ctx, isSet: false, lenIndex: 2, lenSize: 2)) return true;
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,2,2}, "__memcpy");

bool TryEmitMemcpyOrMemsetInline(string funcName, Expr[] args, FunctionContext ctx, bool isSet, int lenIndex, int lenSize)
        {
            args = args ?? Array.Empty<Expr>();
            int expected = isSet ? 3 : 3;
            if (args.Length != expected) return false;
            if (!TryEvaluateConstant(args[lenIndex], out int len)) return false;
            if (len < 0 || len > 32) return false;
            int valueConst = 0;
            if (isSet && !TryEvaluateConstant(args[1], out valueConst)) return false;
            // A zero-length expansion emits no address or fill evaluation in this helper.
            if (len == 0) return true;
            if (isSet)
            {
                int[] ptr = AcquireTemps(2);
                try
                {
                    EmitLoadValue(args[0], ctx, 2);
                    EmitAsm("STA", Mem(ptr[0]));
                    EmitAsm("STX", Mem(ptr[1]));
                    for (int i = 0; i < len; i++)
                    {
                        EmitAsm("LDY", Imm(i));
                        EmitAsm("LDA", Imm(valueConst));
                        EmitAsm("STA", IndY(ptr[0]));
                    }
                }
                finally { ReleaseTemps(ptr); }
                return true;
            }
            EmitFixedMemcpy(args[0], args[1], len, ctx);
            return true;
        }

void EmitHelperMemoryAndBit()
        {
            // Promote the byte count to a word by clearing its high byte before entering memcpy.
            EmitHelperStart("__memcpy_small");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 5));
            EmitAsm("JMP", Abs("__memcpy"));

            // Advance both argument pointers and decrement the word count in place; overlapping copies are not reversed.
            EmitHelperStart("__memcpy");
            string mloop = NewGeneratedLabel("memcpy_loop");
            string mdone = NewGeneratedLabel("memcpy_done");
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("ORA", Mem(CallArgBase + 5));
            EmitAsm("BEQ", Rel(mdone));
            _assembly.Add(Expr.Make(Tag.Label, mloop));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", IndY(CallArgBase + 2));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INC", Mem(CallArgBase + 2));
            string ms1 = NewGeneratedLabel("memcpy_src_page_ok");
            EmitAsm("BNE", Rel(ms1));
            EmitAsm("INC", Mem(CallArgBase + 3));
            _assembly.Add(Expr.Make(Tag.Label, ms1));
            EmitAsm("INC", Mem(CallArgBase));
            string md1 = NewGeneratedLabel("memcpy_dst_page_ok");
            EmitAsm("BNE", Rel(md1));
            EmitAsm("INC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, md1));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            string mlononzero = NewGeneratedLabel("memcpy_lenlo_nonzero");
            EmitAsm("BNE", Rel(mlononzero));
            EmitAsm("DEC", Mem(CallArgBase + 5));
            _assembly.Add(Expr.Make(Tag.Label, mlononzero));
            EmitAsm("DEC", Mem(CallArgBase + 4));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("ORA", Mem(CallArgBase + 5));
            EmitAsm("BNE", Rel(mloop));
            _assembly.Add(Expr.Make(Tag.Label, mdone));
            EmitAsm("RTS");

            // Clear the high count byte for the small-fill wrapper.
            EmitHelperStart("__memset_small");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 4));
            EmitAsm("JMP", Abs("__memset"));

            // Advance the destination pointer while consuming the word count in the shared argument area.
            EmitHelperStart("__memset");
            string sloop = NewGeneratedLabel("memset_loop");
            string sdone = NewGeneratedLabel("memset_done");
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("ORA", Mem(CallArgBase + 4));
            EmitAsm("BEQ", Rel(sdone));
            _assembly.Add(Expr.Make(Tag.Label, sloop));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INC", Mem(CallArgBase));
            string sd1 = NewGeneratedLabel("memset_dst_page_ok");
            EmitAsm("BNE", Rel(sd1));
            EmitAsm("INC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, sd1));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            string slononzero = NewGeneratedLabel("memset_lenlo_nonzero");
            EmitAsm("BNE", Rel(slononzero));
            EmitAsm("DEC", Mem(CallArgBase + 4));
            _assembly.Add(Expr.Make(Tag.Label, slononzero));
            EmitAsm("DEC", Mem(CallArgBase + 3));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("ORA", Mem(CallArgBase + 4));
            EmitAsm("BNE", Rel(sloop));
            _assembly.Add(Expr.Make(Tag.Label, sdone));
            EmitAsm("RTS");
        }

void EmitFixedMemcpy(Expr dstExpr, Expr srcExpr, int len, FunctionContext ctx)
        {
            int[] ptr = AcquireTemps(4);
            try
            {
                EmitLoadValue(dstExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitLoadValue(srcExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[2]));
                EmitAsm("STX", Mem(ptr[3]));
                for (int i = 0; i < len; i++)
                {
                    EmitAsm("LDY", Imm(i));
                    EmitAsm("LDA", IndY(ptr[2]));
                    EmitAsm("STA", IndY(ptr[0]));
                }
            }
            finally { ReleaseTemps(ptr); }
        }

// kitaqfc/kitaqfc/Lowerer.cs:2128
if (expr.MatchAny(Tag.Call, out callFunc, out callArgs))
        {
            string knownCallName;
            if (callFunc != null && callFunc.Match(Tag.Name, out knownCallName) &&
                knownCallName == "__cgb_is_cgb" &&
                callArgs != null && callArgs.Length == 0 &&
                // A resolved target configuration can replace the zero-argument CGB query with a literal.
                Program.TryGetKnownCgbRuntimeValue(out int knownCgbValue))
            {
                return Expr.Make(Tag.Integer, knownCgbValue).WithSource(expr.Source);
            }

            Expr newFunc = LowerExpr(ctx, callFunc, false, prefix);

            // Optimization (post-A3): when we must spill a non-atomic argument into a temp,
            // prefer a u8 temp if the *parameter type* is u8-like.
            // This preserves semantics (implicit truncation to u8) while avoiding needless
            // u16 temporaries created by integer promotions.
            CType[] paramTypes = null;
            string __fname = null;
            if (newFunc.Match(Tag.Name, out __fname))
            {
                paramTypes = ctx.FindFuncParams(__fname);
                if (paramTypes == null)
                {
                    CType fnTypeFromName;
                    if (TryGetCallableFunctionType(ctx.FindTypeOfName(__fname), out fnTypeFromName))
                        paramTypes = fnTypeFromName.ParamTypes;
                }
            }
            else
            {
                CType fnTypeFromExpr;
                if (TryGetCallableFunctionType(InferType(ctx, newFunc), out fnTypeFromExpr))
                    paramTypes = fnTypeFromExpr.ParamTypes;
            }

            Expr[] newArgs = new Expr[callArgs.Length];
            for (int i = 0; i < callArgs.Length; i++)
            {
                Expr a = LowerExpr(ctx, callArgs[i], allowExtract, prefix);

                bool preserveConstantArgIntrinsic = false;
                if (a.MatchAny(Tag.Call, out Expr argFunc, out Expr[] _argCallArgs) &&
                    argFunc.Match(Tag.Name, out string argFuncName))
                {
                    preserveConstantArgIntrinsic = (argFuncName == "__bankof" || argFuncName == "__cgb_is_cgb");
                }
                // Keep evaluable constants and special intrinsic/bank operands visible to code generation instead of spilling them.
                bool preserveCompileTimeConstantArg = ctx.Global.TryEvalConstInt(a, out _);
                bool preserveFarcallBankArg = (__fname == "__farcall" && i == 0);

                if (allowExtract && !preserveFarcallBankArg && !preserveConstantArgIntrinsic && !preserveCompileTimeConstantArg && !IsAtom(a))
                {
                    // If we know the callee's parameter type, use it to choose a smaller temp.
                    // Example: (u8)(row*32) passed to a u8 param should spill as u8, not u16.
                    CType spillAs = null;
                    if (paramTypes != null && i < paramTypes.Length)
                    {
                        CType pt = paramTypes[i];
                        if (IsU8Like(pt)) spillAs = CType.UInt8;
                    }
                    if (spillAs == null) spillAs = InferType(ctx, a);
                    if (!IsAggregateType(spillAs) && SizeOfType(spillAs) <= 2)
                        a = SpillToTemp(ctx, a, spillAs, prefix);
                }
                newArgs[i] = a;
            }

            // Lint: const discard for argument passing
            // Warn when passing a const-qualified pointer (or const array decay) to a non-const pointer parameter.
            // Suppress when the argument has an explicit cast, or inside __unsafe.
            if (!ctx.InUnsafe && paramTypes != null)
            {
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;
                    if (!IsPointerToNonConst(pt)) continue;
                    if (HasTopLevelCast(newArgs[i])) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at != null && (IsPointerToConst(at) || IsArrayOfConst(at)))
                    {
                        string fn = __fname ?? "<call>";
                        WarnConstDiscard(expr, $"argument {i} to '{fn}'");
                        break; // keep it quiet: one warning per call is enough
                    }
                }
            }

            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    FilePosition argPos = newArgs[i].Source;
                    if (string.IsNullOrEmpty(argPos.Filename) || argPos.Filename == "<unknown>")
                        argPos = expr.Source;
                    WarnImplicitNarrowingIfNeeded(ctx, newArgs[i], InferType(ctx, newArgs[i]), paramTypes[i], argPos,
                        "argument " + i + " to '" + fn + "'");
                }
            }

            // Lint: __enum_strict argument passing.
            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at == null) continue;

                    if (HasTopLevelCast(newArgs[i])) continue;

                    if (IsStrictEnum(pt))
                    {
                        if (!IsSameEnum(pt, at))
                        {
                            Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                                "argument {0} to '{1}' expects __enum_strict {2}, got {3}; cast explicitly to silence",
                                i, fn, pt.Show(), at.Show());
                        }
                    }
                    else if (IsPlainInteger(pt) && IsStrictEnum(at))
                    {
                        Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                            "argument {0} to '{1}' passes __enum_strict {2} to integer parameter {3}; cast explicitly to silence",
                            i, fn, at.Show(), pt.Show());
                    }
                }
            }

            if (!ctx.InUnsafe)
                RestrictAliasLint(ctx, newFunc, newArgs, expr.Source);

            // __slice(ptr,len) helper: represent a "slice" (ptr+len) in the IR.
            // Semantics: evaluate both arguments, result type is the pointer/array (same as arg0).
            // Bounds checks are injected only with -Zcheck (see Program.CheckSliceBounds).
            // Note: keep the intrinsic name conservative to avoid collisions ("slice" is allowed only
            // when there is no declared function named "slice").
            if (newFunc.Match(Tag.Name, out string __sfname))
            {
                bool isSliceIntrinsic = (__sfname == "__slice") || (__sfname == "slice" && ctx.FindFuncParams("slice") == null);
                if (isSliceIntrinsic)
                {
                    if (newArgs.Length != 2)
                    {
                        Program.Error(expr.Source, ErrorCode.ParseError, "{0}: expected 2 arguments: __slice(ptr,len)", __sfname);
                    }
                    else
                    {
                        CType pty = InferType(ctx, newArgs[0]);
                        if (pty == null || !(pty.IsPointer || pty.IsArray))
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: first argument must be a pointer or array, got: {1}", __sfname, (pty == null ? "<unknown>" : pty.Show()));

                        CType lty = InferType(ctx, newArgs[1]);
                        if (lty == null || !lty.IsInteger)
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: second argument must be an integer length, got: {1}", __sfname, (lty == null ? "<unknown>" : lty.Show()));
                    }

                    return Expr.Make(Tag.Slice, newArgs[0], newArgs[1]).WithSource(expr.Source);
                }
            }

            return MakeCall(newFunc, newArgs).WithSource(expr.Source);
        }

Copie un bloc d’au plus 255 octets avec un compteur sur 8 bits. Choisissez cette forme lorsque la longueur tient dans un octet. _small désigne la largeur du compteur ; ce nom ne garantit ni une durée d’exécution ni une taille de code précises.

Syntaxe

void __memcpy_small(u8* dst, const u8* src, u8 len);

Paramètres

dst

Pointeur vers le premier octet accessible en écriture de la destination. Prévoyez une zone contiguë assez grande pour toute l’opération ; aucun tampon n’est alloué automatiquement.

src

Pointeur vers le premier octet lisible de la source. Toute la zone doit rester accessible et inchangée pendant la copie.

len

Nombre d’octets en u8 : 0–255. Ne passez pas 256 pour désigner un bloc entier de 256 octets : cette longueur ne tient pas dans le paramètre. À partir de 256 octets, utilisez la fonction correspondante sans _small.

Valeur renvoyée

Aucune (void).

Conditions et limites

Un compteur nul ne transfère aucun octet. Les effets de bord des expressions passées en argument ont néanmoins lieu : l’exemple fournit deux fonctions renvoyant des pointeurs et constate leurs deux appels malgré une longueur nulle.

Utilisez des zones source et destination sans chevauchement. Ces routines copient vers les adresses croissantes et n’offrent pas la sécurité de memmove en cas de recouvrement ; écraser une partie de la source encore non lue peut altérer la suite de la copie.

L’opération se termine avant de rendre la main. Elle ne change pas de banque ROM/RAM et ne limite pas automatiquement la zone aux bornes d’un tampon. Maintenez le mappage stable, utilisez des zones valides et coordonnez l’accès avec les interruptions utilisant les mêmes tampons.

Sur FC, dst est une adresse CPU, pas une adresse PPU. Une copie en RAM CPU ne modifie ni CHR, ni les tables de noms, ni les palettes ; leur chargement nécessite les API PPU/VRAM. Les routines auxiliaires générées partagent les arguments et les temporaires : ne les rappelez pas depuis une NMI/IRQ pendant une opération en cours.

Exemple d’utilisation

memory_reset();
__memcpy_small(memory_destination+1,memory_source+1,255);
memory_copy_byte=memory_check(255,0); // Maximum representable byte count.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet exemple utilise __memcpy_small pour copier 255 octets suivant un motif connu à partir du décalage 1. memory_check compare les tableaux source et destination en entier ; la ligne COPY BYTE doit afficher 255. Le premier octet sert de garde et les octets suivant le bloc doivent également rester inchangés.

Le programme complet initialise deux tampons de 264 octets avant chaque opération, puis vérifie tous les octets de la source, de la destination et des zones de garde. L’écran attendu affiche COPY WORD 257, FILL WORD 257, COPY BYTE 255, FILL BYTE 255, COPY16 016, COPY32 032, ZERO CALLS 002 et FAILED 000. WORD/BYTE désignent la largeur du compteur, pas la taille des éléments copiés. Ces nombres proviennent des vérifications de l’exemple ; ces fonctions void ne renvoient aucune valeur.

Les captures montrent du texte noir sur blanc sur DMG, bleu sur blanc sur CGB et bleu sur noir sur FC. L’exemple vérifie des opérations en RAM ; le texte en présente les résultats, sans illustrer une primitive de dessin. Des contrôles distincts sur émulateur couvrent 88 cas par plateforme : longueurs constantes ou déterminées à l’exécution de 0, 1, 16, 17, 32, 33, 64, 65 et 255 octets, plus 256 et 257 pour les compteurs sur 16 bits. Aucun test sur matériel réel n’a été effectué.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\memory_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\memory_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Forward copy with an 8-bit length, zero through 255; the dynamic helper promotes it to a word count.

case "__memcpy_small":
                    if (TryEmitMemcpyOrMemsetInline(funcName, args, ctx, isSet: false, lenIndex: 2, lenSize: 1)) return true;
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,2,1}, "__memcpy_small");

bool TryEmitMemcpyOrMemsetInline(string funcName, Expr[] args, FunctionContext ctx, bool isSet, int lenIndex, int lenSize)
        {
            args = args ?? Array.Empty<Expr>();
            int expected = isSet ? 3 : 3;
            if (args.Length != expected) return false;
            if (!TryEvaluateConstant(args[lenIndex], out int len)) return false;
            if (len < 0 || len > 32) return false;
            int valueConst = 0;
            if (isSet && !TryEvaluateConstant(args[1], out valueConst)) return false;
            // A zero-length expansion emits no address or fill evaluation in this helper.
            if (len == 0) return true;
            if (isSet)
            {
                int[] ptr = AcquireTemps(2);
                try
                {
                    EmitLoadValue(args[0], ctx, 2);
                    EmitAsm("STA", Mem(ptr[0]));
                    EmitAsm("STX", Mem(ptr[1]));
                    for (int i = 0; i < len; i++)
                    {
                        EmitAsm("LDY", Imm(i));
                        EmitAsm("LDA", Imm(valueConst));
                        EmitAsm("STA", IndY(ptr[0]));
                    }
                }
                finally { ReleaseTemps(ptr); }
                return true;
            }
            EmitFixedMemcpy(args[0], args[1], len, ctx);
            return true;
        }

void EmitHelperMemoryAndBit()
        {
            // Promote the byte count to a word by clearing its high byte before entering memcpy.
            EmitHelperStart("__memcpy_small");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 5));
            EmitAsm("JMP", Abs("__memcpy"));

            // Advance both argument pointers and decrement the word count in place; overlapping copies are not reversed.
            EmitHelperStart("__memcpy");
            string mloop = NewGeneratedLabel("memcpy_loop");
            string mdone = NewGeneratedLabel("memcpy_done");
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("ORA", Mem(CallArgBase + 5));
            EmitAsm("BEQ", Rel(mdone));
            _assembly.Add(Expr.Make(Tag.Label, mloop));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", IndY(CallArgBase + 2));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INC", Mem(CallArgBase + 2));
            string ms1 = NewGeneratedLabel("memcpy_src_page_ok");
            EmitAsm("BNE", Rel(ms1));
            EmitAsm("INC", Mem(CallArgBase + 3));
            _assembly.Add(Expr.Make(Tag.Label, ms1));
            EmitAsm("INC", Mem(CallArgBase));
            string md1 = NewGeneratedLabel("memcpy_dst_page_ok");
            EmitAsm("BNE", Rel(md1));
            EmitAsm("INC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, md1));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            string mlononzero = NewGeneratedLabel("memcpy_lenlo_nonzero");
            EmitAsm("BNE", Rel(mlononzero));
            EmitAsm("DEC", Mem(CallArgBase + 5));
            _assembly.Add(Expr.Make(Tag.Label, mlononzero));
            EmitAsm("DEC", Mem(CallArgBase + 4));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("ORA", Mem(CallArgBase + 5));
            EmitAsm("BNE", Rel(mloop));
            _assembly.Add(Expr.Make(Tag.Label, mdone));
            EmitAsm("RTS");

            // Clear the high count byte for the small-fill wrapper.
            EmitHelperStart("__memset_small");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 4));
            EmitAsm("JMP", Abs("__memset"));

            // Advance the destination pointer while consuming the word count in the shared argument area.
            EmitHelperStart("__memset");
            string sloop = NewGeneratedLabel("memset_loop");
            string sdone = NewGeneratedLabel("memset_done");
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("ORA", Mem(CallArgBase + 4));
            EmitAsm("BEQ", Rel(sdone));
            _assembly.Add(Expr.Make(Tag.Label, sloop));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INC", Mem(CallArgBase));
            string sd1 = NewGeneratedLabel("memset_dst_page_ok");
            EmitAsm("BNE", Rel(sd1));
            EmitAsm("INC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, sd1));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            string slononzero = NewGeneratedLabel("memset_lenlo_nonzero");
            EmitAsm("BNE", Rel(slononzero));
            EmitAsm("DEC", Mem(CallArgBase + 4));
            _assembly.Add(Expr.Make(Tag.Label, slononzero));
            EmitAsm("DEC", Mem(CallArgBase + 3));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("ORA", Mem(CallArgBase + 4));
            EmitAsm("BNE", Rel(sloop));
            _assembly.Add(Expr.Make(Tag.Label, sdone));
            EmitAsm("RTS");
        }

void EmitFixedMemcpy(Expr dstExpr, Expr srcExpr, int len, FunctionContext ctx)
        {
            int[] ptr = AcquireTemps(4);
            try
            {
                EmitLoadValue(dstExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitLoadValue(srcExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[2]));
                EmitAsm("STX", Mem(ptr[3]));
                for (int i = 0; i < len; i++)
                {
                    EmitAsm("LDY", Imm(i));
                    EmitAsm("LDA", IndY(ptr[2]));
                    EmitAsm("STA", IndY(ptr[0]));
                }
            }
            finally { ReleaseTemps(ptr); }
        }

// kitaqfc/kitaqfc/Lowerer.cs:2128
if (expr.MatchAny(Tag.Call, out callFunc, out callArgs))
        {
            string knownCallName;
            if (callFunc != null && callFunc.Match(Tag.Name, out knownCallName) &&
                knownCallName == "__cgb_is_cgb" &&
                callArgs != null && callArgs.Length == 0 &&
                // A resolved target configuration can replace the zero-argument CGB query with a literal.
                Program.TryGetKnownCgbRuntimeValue(out int knownCgbValue))
            {
                return Expr.Make(Tag.Integer, knownCgbValue).WithSource(expr.Source);
            }

            Expr newFunc = LowerExpr(ctx, callFunc, false, prefix);

            // Optimization (post-A3): when we must spill a non-atomic argument into a temp,
            // prefer a u8 temp if the *parameter type* is u8-like.
            // This preserves semantics (implicit truncation to u8) while avoiding needless
            // u16 temporaries created by integer promotions.
            CType[] paramTypes = null;
            string __fname = null;
            if (newFunc.Match(Tag.Name, out __fname))
            {
                paramTypes = ctx.FindFuncParams(__fname);
                if (paramTypes == null)
                {
                    CType fnTypeFromName;
                    if (TryGetCallableFunctionType(ctx.FindTypeOfName(__fname), out fnTypeFromName))
                        paramTypes = fnTypeFromName.ParamTypes;
                }
            }
            else
            {
                CType fnTypeFromExpr;
                if (TryGetCallableFunctionType(InferType(ctx, newFunc), out fnTypeFromExpr))
                    paramTypes = fnTypeFromExpr.ParamTypes;
            }

            Expr[] newArgs = new Expr[callArgs.Length];
            for (int i = 0; i < callArgs.Length; i++)
            {
                Expr a = LowerExpr(ctx, callArgs[i], allowExtract, prefix);

                bool preserveConstantArgIntrinsic = false;
                if (a.MatchAny(Tag.Call, out Expr argFunc, out Expr[] _argCallArgs) &&
                    argFunc.Match(Tag.Name, out string argFuncName))
                {
                    preserveConstantArgIntrinsic = (argFuncName == "__bankof" || argFuncName == "__cgb_is_cgb");
                }
                // Keep evaluable constants and special intrinsic/bank operands visible to code generation instead of spilling them.
                bool preserveCompileTimeConstantArg = ctx.Global.TryEvalConstInt(a, out _);
                bool preserveFarcallBankArg = (__fname == "__farcall" && i == 0);

                if (allowExtract && !preserveFarcallBankArg && !preserveConstantArgIntrinsic && !preserveCompileTimeConstantArg && !IsAtom(a))
                {
                    // If we know the callee's parameter type, use it to choose a smaller temp.
                    // Example: (u8)(row*32) passed to a u8 param should spill as u8, not u16.
                    CType spillAs = null;
                    if (paramTypes != null && i < paramTypes.Length)
                    {
                        CType pt = paramTypes[i];
                        if (IsU8Like(pt)) spillAs = CType.UInt8;
                    }
                    if (spillAs == null) spillAs = InferType(ctx, a);
                    if (!IsAggregateType(spillAs) && SizeOfType(spillAs) <= 2)
                        a = SpillToTemp(ctx, a, spillAs, prefix);
                }
                newArgs[i] = a;
            }

            // Lint: const discard for argument passing
            // Warn when passing a const-qualified pointer (or const array decay) to a non-const pointer parameter.
            // Suppress when the argument has an explicit cast, or inside __unsafe.
            if (!ctx.InUnsafe && paramTypes != null)
            {
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;
                    if (!IsPointerToNonConst(pt)) continue;
                    if (HasTopLevelCast(newArgs[i])) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at != null && (IsPointerToConst(at) || IsArrayOfConst(at)))
                    {
                        string fn = __fname ?? "<call>";
                        WarnConstDiscard(expr, $"argument {i} to '{fn}'");
                        break; // keep it quiet: one warning per call is enough
                    }
                }
            }

            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    FilePosition argPos = newArgs[i].Source;
                    if (string.IsNullOrEmpty(argPos.Filename) || argPos.Filename == "<unknown>")
                        argPos = expr.Source;
                    WarnImplicitNarrowingIfNeeded(ctx, newArgs[i], InferType(ctx, newArgs[i]), paramTypes[i], argPos,
                        "argument " + i + " to '" + fn + "'");
                }
            }

            // Lint: __enum_strict argument passing.
            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at == null) continue;

                    if (HasTopLevelCast(newArgs[i])) continue;

                    if (IsStrictEnum(pt))
                    {
                        if (!IsSameEnum(pt, at))
                        {
                            Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                                "argument {0} to '{1}' expects __enum_strict {2}, got {3}; cast explicitly to silence",
                                i, fn, pt.Show(), at.Show());
                        }
                    }
                    else if (IsPlainInteger(pt) && IsStrictEnum(at))
                    {
                        Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                            "argument {0} to '{1}' passes __enum_strict {2} to integer parameter {3}; cast explicitly to silence",
                            i, fn, at.Show(), pt.Show());
                    }
                }
            }

            if (!ctx.InUnsafe)
                RestrictAliasLint(ctx, newFunc, newArgs, expr.Source);

            // __slice(ptr,len) helper: represent a "slice" (ptr+len) in the IR.
            // Semantics: evaluate both arguments, result type is the pointer/array (same as arg0).
            // Bounds checks are injected only with -Zcheck (see Program.CheckSliceBounds).
            // Note: keep the intrinsic name conservative to avoid collisions ("slice" is allowed only
            // when there is no declared function named "slice").
            if (newFunc.Match(Tag.Name, out string __sfname))
            {
                bool isSliceIntrinsic = (__sfname == "__slice") || (__sfname == "slice" && ctx.FindFuncParams("slice") == null);
                if (isSliceIntrinsic)
                {
                    if (newArgs.Length != 2)
                    {
                        Program.Error(expr.Source, ErrorCode.ParseError, "{0}: expected 2 arguments: __slice(ptr,len)", __sfname);
                    }
                    else
                    {
                        CType pty = InferType(ctx, newArgs[0]);
                        if (pty == null || !(pty.IsPointer || pty.IsArray))
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: first argument must be a pointer or array, got: {1}", __sfname, (pty == null ? "<unknown>" : pty.Show()));

                        CType lty = InferType(ctx, newArgs[1]);
                        if (lty == null || !lty.IsInteger)
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: second argument must be an integer length, got: {1}", __sfname, (lty == null ? "<unknown>" : lty.Show()));
                    }

                    return Expr.Make(Tag.Slice, newArgs[0], newArgs[1]).WithSource(expr.Source);
                }
            }

            return MakeCall(newFunc, newArgs).WithSource(expr.Source);
        }

Remplit la zone de destination avec une même valeur d’un octet. Le compteur sur 16 bits convient à l’effacement d’un grand tampon ou à l’initialisation d’une table. Par exemple, 0x5A écrit 5A 5A 5A…, et non un entier de plusieurs octets répété.

Syntaxe

void __memset(u8* dst, u8 value, u16 len);

Paramètres

dst

Pointeur vers le premier octet accessible en écriture de la destination. Prévoyez une zone contiguë assez grande pour toute l’opération ; aucun tampon n’est alloué automatiquement.

value

Octet répété à chaque adresse de destination : 0–255. La valeur 0 remet la zone à zéro. Pour initialiser un tableau de u16 avec un nombre non nul, affectez ce nombre à chaque élément.

len

Nombre d’octets en u16 (0–65535), et non nombre d’éléments. Le maximum du type ne garantit pas que la machine dispose d’un tampon valide de cette taille. Toute la zone doit tenir dans le mappage mémoire sélectionné.

Valeur renvoyée

Aucune (void).

Conditions et limites

Un compteur nul ne transfère aucun octet. Les effets de bord des expressions passées en argument ont néanmoins lieu : l’exemple fournit deux fonctions renvoyant des pointeurs et constate leurs deux appels malgré une longueur nulle.

L’opération se termine avant de rendre la main. Elle ne change pas de banque ROM/RAM et ne limite pas automatiquement la zone aux bornes d’un tampon. Maintenez le mappage stable, utilisez des zones valides et coordonnez l’accès avec les interruptions utilisant les mêmes tampons.

Sur FC, dst est une adresse CPU, pas une adresse PPU. Une copie en RAM CPU ne modifie ni CHR, ni les tables de noms, ni les palettes ; leur chargement nécessite les API PPU/VRAM. Les routines auxiliaires générées partagent les arguments et les temporaires : ne les rappelez pas depuis une NMI/IRQ pendant une opération en cours.

Exemple d’utilisation

memory_reset();
__memset(memory_destination+1,0x5A,257);
memory_fill_word=memory_check(257,1); // Repeat one byte, not a 16-bit word.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet exemple utilise __memset pour remplir 257 octets avec 0x5A à partir du décalage 1. memory_check exige que tous ces octets valent 0x5A, que les octets de garde restent à 0xCC et que le tampon source distinct ne change pas. La ligne FILL WORD doit afficher 257.

Le programme complet initialise deux tampons de 264 octets avant chaque opération, puis vérifie tous les octets de la source, de la destination et des zones de garde. L’écran attendu affiche COPY WORD 257, FILL WORD 257, COPY BYTE 255, FILL BYTE 255, COPY16 016, COPY32 032, ZERO CALLS 002 et FAILED 000. WORD/BYTE désignent la largeur du compteur, pas la taille des éléments copiés. Ces nombres proviennent des vérifications de l’exemple ; ces fonctions void ne renvoient aucune valeur.

Les captures montrent du texte noir sur blanc sur DMG, bleu sur blanc sur CGB et bleu sur noir sur FC. L’exemple vérifie des opérations en RAM ; le texte en présente les résultats, sans illustrer une primitive de dessin. Des contrôles distincts sur émulateur couvrent 88 cas par plateforme : longueurs constantes ou déterminées à l’exécution de 0, 1, 16, 17, 32, 33, 64, 65 et 255 octets, plus 256 et 257 pour les compteurs sur 16 bits. Aucun test sur matériel réel n’a été effectué.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\memory_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\memory_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Fill len CPU bytes with value. Zero length still evaluates argument side effects.

case "__memset":
                    if (TryEmitMemcpyOrMemsetInline(funcName, args, ctx, isSet: true, lenIndex: 2, lenSize: 2)) return true;
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,1,2}, "__memset");

bool TryEmitMemcpyOrMemsetInline(string funcName, Expr[] args, FunctionContext ctx, bool isSet, int lenIndex, int lenSize)
        {
            args = args ?? Array.Empty<Expr>();
            int expected = isSet ? 3 : 3;
            if (args.Length != expected) return false;
            if (!TryEvaluateConstant(args[lenIndex], out int len)) return false;
            if (len < 0 || len > 32) return false;
            int valueConst = 0;
            if (isSet && !TryEvaluateConstant(args[1], out valueConst)) return false;
            // A zero-length expansion emits no address or fill evaluation in this helper.
            if (len == 0) return true;
            if (isSet)
            {
                int[] ptr = AcquireTemps(2);
                try
                {
                    EmitLoadValue(args[0], ctx, 2);
                    EmitAsm("STA", Mem(ptr[0]));
                    EmitAsm("STX", Mem(ptr[1]));
                    for (int i = 0; i < len; i++)
                    {
                        EmitAsm("LDY", Imm(i));
                        EmitAsm("LDA", Imm(valueConst));
                        EmitAsm("STA", IndY(ptr[0]));
                    }
                }
                finally { ReleaseTemps(ptr); }
                return true;
            }
            EmitFixedMemcpy(args[0], args[1], len, ctx);
            return true;
        }

void EmitHelperMemoryAndBit()
        {
            // Promote the byte count to a word by clearing its high byte before entering memcpy.
            EmitHelperStart("__memcpy_small");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 5));
            EmitAsm("JMP", Abs("__memcpy"));

            // Advance both argument pointers and decrement the word count in place; overlapping copies are not reversed.
            EmitHelperStart("__memcpy");
            string mloop = NewGeneratedLabel("memcpy_loop");
            string mdone = NewGeneratedLabel("memcpy_done");
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("ORA", Mem(CallArgBase + 5));
            EmitAsm("BEQ", Rel(mdone));
            _assembly.Add(Expr.Make(Tag.Label, mloop));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", IndY(CallArgBase + 2));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INC", Mem(CallArgBase + 2));
            string ms1 = NewGeneratedLabel("memcpy_src_page_ok");
            EmitAsm("BNE", Rel(ms1));
            EmitAsm("INC", Mem(CallArgBase + 3));
            _assembly.Add(Expr.Make(Tag.Label, ms1));
            EmitAsm("INC", Mem(CallArgBase));
            string md1 = NewGeneratedLabel("memcpy_dst_page_ok");
            EmitAsm("BNE", Rel(md1));
            EmitAsm("INC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, md1));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            string mlononzero = NewGeneratedLabel("memcpy_lenlo_nonzero");
            EmitAsm("BNE", Rel(mlononzero));
            EmitAsm("DEC", Mem(CallArgBase + 5));
            _assembly.Add(Expr.Make(Tag.Label, mlononzero));
            EmitAsm("DEC", Mem(CallArgBase + 4));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("ORA", Mem(CallArgBase + 5));
            EmitAsm("BNE", Rel(mloop));
            _assembly.Add(Expr.Make(Tag.Label, mdone));
            EmitAsm("RTS");

            // Clear the high count byte for the small-fill wrapper.
            EmitHelperStart("__memset_small");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 4));
            EmitAsm("JMP", Abs("__memset"));

            // Advance the destination pointer while consuming the word count in the shared argument area.
            EmitHelperStart("__memset");
            string sloop = NewGeneratedLabel("memset_loop");
            string sdone = NewGeneratedLabel("memset_done");
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("ORA", Mem(CallArgBase + 4));
            EmitAsm("BEQ", Rel(sdone));
            _assembly.Add(Expr.Make(Tag.Label, sloop));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INC", Mem(CallArgBase));
            string sd1 = NewGeneratedLabel("memset_dst_page_ok");
            EmitAsm("BNE", Rel(sd1));
            EmitAsm("INC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, sd1));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            string slononzero = NewGeneratedLabel("memset_lenlo_nonzero");
            EmitAsm("BNE", Rel(slononzero));
            EmitAsm("DEC", Mem(CallArgBase + 4));
            _assembly.Add(Expr.Make(Tag.Label, slononzero));
            EmitAsm("DEC", Mem(CallArgBase + 3));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("ORA", Mem(CallArgBase + 4));
            EmitAsm("BNE", Rel(sloop));
            _assembly.Add(Expr.Make(Tag.Label, sdone));
            EmitAsm("RTS");
        }

void EmitFixedMemcpy(Expr dstExpr, Expr srcExpr, int len, FunctionContext ctx)
        {
            int[] ptr = AcquireTemps(4);
            try
            {
                EmitLoadValue(dstExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitLoadValue(srcExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[2]));
                EmitAsm("STX", Mem(ptr[3]));
                for (int i = 0; i < len; i++)
                {
                    EmitAsm("LDY", Imm(i));
                    EmitAsm("LDA", IndY(ptr[2]));
                    EmitAsm("STA", IndY(ptr[0]));
                }
            }
            finally { ReleaseTemps(ptr); }
        }

// kitaqfc/kitaqfc/Lowerer.cs:2128
if (expr.MatchAny(Tag.Call, out callFunc, out callArgs))
        {
            string knownCallName;
            if (callFunc != null && callFunc.Match(Tag.Name, out knownCallName) &&
                knownCallName == "__cgb_is_cgb" &&
                callArgs != null && callArgs.Length == 0 &&
                // A resolved target configuration can replace the zero-argument CGB query with a literal.
                Program.TryGetKnownCgbRuntimeValue(out int knownCgbValue))
            {
                return Expr.Make(Tag.Integer, knownCgbValue).WithSource(expr.Source);
            }

            Expr newFunc = LowerExpr(ctx, callFunc, false, prefix);

            // Optimization (post-A3): when we must spill a non-atomic argument into a temp,
            // prefer a u8 temp if the *parameter type* is u8-like.
            // This preserves semantics (implicit truncation to u8) while avoiding needless
            // u16 temporaries created by integer promotions.
            CType[] paramTypes = null;
            string __fname = null;
            if (newFunc.Match(Tag.Name, out __fname))
            {
                paramTypes = ctx.FindFuncParams(__fname);
                if (paramTypes == null)
                {
                    CType fnTypeFromName;
                    if (TryGetCallableFunctionType(ctx.FindTypeOfName(__fname), out fnTypeFromName))
                        paramTypes = fnTypeFromName.ParamTypes;
                }
            }
            else
            {
                CType fnTypeFromExpr;
                if (TryGetCallableFunctionType(InferType(ctx, newFunc), out fnTypeFromExpr))
                    paramTypes = fnTypeFromExpr.ParamTypes;
            }

            Expr[] newArgs = new Expr[callArgs.Length];
            for (int i = 0; i < callArgs.Length; i++)
            {
                Expr a = LowerExpr(ctx, callArgs[i], allowExtract, prefix);

                bool preserveConstantArgIntrinsic = false;
                if (a.MatchAny(Tag.Call, out Expr argFunc, out Expr[] _argCallArgs) &&
                    argFunc.Match(Tag.Name, out string argFuncName))
                {
                    preserveConstantArgIntrinsic = (argFuncName == "__bankof" || argFuncName == "__cgb_is_cgb");
                }
                // Keep evaluable constants and special intrinsic/bank operands visible to code generation instead of spilling them.
                bool preserveCompileTimeConstantArg = ctx.Global.TryEvalConstInt(a, out _);
                bool preserveFarcallBankArg = (__fname == "__farcall" && i == 0);

                if (allowExtract && !preserveFarcallBankArg && !preserveConstantArgIntrinsic && !preserveCompileTimeConstantArg && !IsAtom(a))
                {
                    // If we know the callee's parameter type, use it to choose a smaller temp.
                    // Example: (u8)(row*32) passed to a u8 param should spill as u8, not u16.
                    CType spillAs = null;
                    if (paramTypes != null && i < paramTypes.Length)
                    {
                        CType pt = paramTypes[i];
                        if (IsU8Like(pt)) spillAs = CType.UInt8;
                    }
                    if (spillAs == null) spillAs = InferType(ctx, a);
                    if (!IsAggregateType(spillAs) && SizeOfType(spillAs) <= 2)
                        a = SpillToTemp(ctx, a, spillAs, prefix);
                }
                newArgs[i] = a;
            }

            // Lint: const discard for argument passing
            // Warn when passing a const-qualified pointer (or const array decay) to a non-const pointer parameter.
            // Suppress when the argument has an explicit cast, or inside __unsafe.
            if (!ctx.InUnsafe && paramTypes != null)
            {
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;
                    if (!IsPointerToNonConst(pt)) continue;
                    if (HasTopLevelCast(newArgs[i])) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at != null && (IsPointerToConst(at) || IsArrayOfConst(at)))
                    {
                        string fn = __fname ?? "<call>";
                        WarnConstDiscard(expr, $"argument {i} to '{fn}'");
                        break; // keep it quiet: one warning per call is enough
                    }
                }
            }

            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    FilePosition argPos = newArgs[i].Source;
                    if (string.IsNullOrEmpty(argPos.Filename) || argPos.Filename == "<unknown>")
                        argPos = expr.Source;
                    WarnImplicitNarrowingIfNeeded(ctx, newArgs[i], InferType(ctx, newArgs[i]), paramTypes[i], argPos,
                        "argument " + i + " to '" + fn + "'");
                }
            }

            // Lint: __enum_strict argument passing.
            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at == null) continue;

                    if (HasTopLevelCast(newArgs[i])) continue;

                    if (IsStrictEnum(pt))
                    {
                        if (!IsSameEnum(pt, at))
                        {
                            Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                                "argument {0} to '{1}' expects __enum_strict {2}, got {3}; cast explicitly to silence",
                                i, fn, pt.Show(), at.Show());
                        }
                    }
                    else if (IsPlainInteger(pt) && IsStrictEnum(at))
                    {
                        Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                            "argument {0} to '{1}' passes __enum_strict {2} to integer parameter {3}; cast explicitly to silence",
                            i, fn, at.Show(), pt.Show());
                    }
                }
            }

            if (!ctx.InUnsafe)
                RestrictAliasLint(ctx, newFunc, newArgs, expr.Source);

            // __slice(ptr,len) helper: represent a "slice" (ptr+len) in the IR.
            // Semantics: evaluate both arguments, result type is the pointer/array (same as arg0).
            // Bounds checks are injected only with -Zcheck (see Program.CheckSliceBounds).
            // Note: keep the intrinsic name conservative to avoid collisions ("slice" is allowed only
            // when there is no declared function named "slice").
            if (newFunc.Match(Tag.Name, out string __sfname))
            {
                bool isSliceIntrinsic = (__sfname == "__slice") || (__sfname == "slice" && ctx.FindFuncParams("slice") == null);
                if (isSliceIntrinsic)
                {
                    if (newArgs.Length != 2)
                    {
                        Program.Error(expr.Source, ErrorCode.ParseError, "{0}: expected 2 arguments: __slice(ptr,len)", __sfname);
                    }
                    else
                    {
                        CType pty = InferType(ctx, newArgs[0]);
                        if (pty == null || !(pty.IsPointer || pty.IsArray))
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: first argument must be a pointer or array, got: {1}", __sfname, (pty == null ? "<unknown>" : pty.Show()));

                        CType lty = InferType(ctx, newArgs[1]);
                        if (lty == null || !lty.IsInteger)
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: second argument must be an integer length, got: {1}", __sfname, (lty == null ? "<unknown>" : lty.Show()));
                    }

                    return Expr.Make(Tag.Slice, newArgs[0], newArgs[1]).WithSource(expr.Source);
                }
            }

            return MakeCall(newFunc, newArgs).WithSource(expr.Source);
        }

Remplit jusqu’à 255 octets consécutifs avec une même valeur, à l’aide d’un compteur sur 8 bits. Cette forme convient à l’initialisation d’un petit tampon de travail. Au-delà de 255 octets, utilisez __memset.

Syntaxe

void __memset_small(u8* dst, u8 value, u8 len);

Paramètres

dst

Pointeur vers le premier octet accessible en écriture de la destination. Prévoyez une zone contiguë assez grande pour toute l’opération ; aucun tampon n’est alloué automatiquement.

value

Octet répété à chaque adresse de destination : 0–255. La valeur 0 remet la zone à zéro. Pour initialiser un tableau de u16 avec un nombre non nul, affectez ce nombre à chaque élément.

len

Nombre d’octets en u8 : 0–255. Ne passez pas 256 pour désigner un bloc entier de 256 octets : cette longueur ne tient pas dans le paramètre. À partir de 256 octets, utilisez la fonction correspondante sans _small.

Valeur renvoyée

Aucune (void).

Conditions et limites

Un compteur nul ne transfère aucun octet. Les effets de bord des expressions passées en argument ont néanmoins lieu : l’exemple fournit deux fonctions renvoyant des pointeurs et constate leurs deux appels malgré une longueur nulle.

L’opération se termine avant de rendre la main. Elle ne change pas de banque ROM/RAM et ne limite pas automatiquement la zone aux bornes d’un tampon. Maintenez le mappage stable, utilisez des zones valides et coordonnez l’accès avec les interruptions utilisant les mêmes tampons.

Sur FC, dst est une adresse CPU, pas une adresse PPU. Une copie en RAM CPU ne modifie ni CHR, ni les tables de noms, ni les palettes ; leur chargement nécessite les API PPU/VRAM. Les routines auxiliaires générées partagent les arguments et les temporaires : ne les rappelez pas depuis une NMI/IRQ pendant une opération en cours.

Exemple d’utilisation

memory_reset();
__memset_small(memory_destination+1,0x5A,255);
memory_fill_byte=memory_check(255,1);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet exemple utilise __memset_small pour remplir 255 octets avec 0x5A à partir du décalage 1. memory_check exige que tous ces octets valent 0x5A, que les octets de garde restent à 0xCC et que le tampon source distinct ne change pas. La ligne FILL BYTE doit afficher 255.

Le programme complet initialise deux tampons de 264 octets avant chaque opération, puis vérifie tous les octets de la source, de la destination et des zones de garde. L’écran attendu affiche COPY WORD 257, FILL WORD 257, COPY BYTE 255, FILL BYTE 255, COPY16 016, COPY32 032, ZERO CALLS 002 et FAILED 000. WORD/BYTE désignent la largeur du compteur, pas la taille des éléments copiés. Ces nombres proviennent des vérifications de l’exemple ; ces fonctions void ne renvoient aucune valeur.

Les captures montrent du texte noir sur blanc sur DMG, bleu sur blanc sur CGB et bleu sur noir sur FC. L’exemple vérifie des opérations en RAM ; le texte en présente les résultats, sans illustrer une primitive de dessin. Des contrôles distincts sur émulateur couvrent 88 cas par plateforme : longueurs constantes ou déterminées à l’exécution de 0, 1, 16, 17, 32, 33, 64, 65 et 255 octets, plus 256 et 257 pour les compteurs sur 16 bits. Aucun test sur matériel réel n’a été effectué.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\memory_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\memory_intrinsics.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Fill zero through 255 CPU bytes; this is ordinary RAM access, not a PPU transfer.

case "__memset_small":
                    if (TryEmitMemcpyOrMemsetInline(funcName, args, ctx, isSet: true, lenIndex: 2, lenSize: 1)) return true;
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,1,1}, "__memset_small");
                // These fixed-size copies bypass the variable-length helper argument area.

bool TryEmitMemcpyOrMemsetInline(string funcName, Expr[] args, FunctionContext ctx, bool isSet, int lenIndex, int lenSize)
        {
            args = args ?? Array.Empty<Expr>();
            int expected = isSet ? 3 : 3;
            if (args.Length != expected) return false;
            if (!TryEvaluateConstant(args[lenIndex], out int len)) return false;
            if (len < 0 || len > 32) return false;
            int valueConst = 0;
            if (isSet && !TryEvaluateConstant(args[1], out valueConst)) return false;
            // A zero-length expansion emits no address or fill evaluation in this helper.
            if (len == 0) return true;
            if (isSet)
            {
                int[] ptr = AcquireTemps(2);
                try
                {
                    EmitLoadValue(args[0], ctx, 2);
                    EmitAsm("STA", Mem(ptr[0]));
                    EmitAsm("STX", Mem(ptr[1]));
                    for (int i = 0; i < len; i++)
                    {
                        EmitAsm("LDY", Imm(i));
                        EmitAsm("LDA", Imm(valueConst));
                        EmitAsm("STA", IndY(ptr[0]));
                    }
                }
                finally { ReleaseTemps(ptr); }
                return true;
            }
            EmitFixedMemcpy(args[0], args[1], len, ctx);
            return true;
        }

void EmitHelperMemoryAndBit()
        {
            // Promote the byte count to a word by clearing its high byte before entering memcpy.
            EmitHelperStart("__memcpy_small");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 5));
            EmitAsm("JMP", Abs("__memcpy"));

            // Advance both argument pointers and decrement the word count in place; overlapping copies are not reversed.
            EmitHelperStart("__memcpy");
            string mloop = NewGeneratedLabel("memcpy_loop");
            string mdone = NewGeneratedLabel("memcpy_done");
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("ORA", Mem(CallArgBase + 5));
            EmitAsm("BEQ", Rel(mdone));
            _assembly.Add(Expr.Make(Tag.Label, mloop));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", IndY(CallArgBase + 2));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INC", Mem(CallArgBase + 2));
            string ms1 = NewGeneratedLabel("memcpy_src_page_ok");
            EmitAsm("BNE", Rel(ms1));
            EmitAsm("INC", Mem(CallArgBase + 3));
            _assembly.Add(Expr.Make(Tag.Label, ms1));
            EmitAsm("INC", Mem(CallArgBase));
            string md1 = NewGeneratedLabel("memcpy_dst_page_ok");
            EmitAsm("BNE", Rel(md1));
            EmitAsm("INC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, md1));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            string mlononzero = NewGeneratedLabel("memcpy_lenlo_nonzero");
            EmitAsm("BNE", Rel(mlononzero));
            EmitAsm("DEC", Mem(CallArgBase + 5));
            _assembly.Add(Expr.Make(Tag.Label, mlononzero));
            EmitAsm("DEC", Mem(CallArgBase + 4));
            EmitAsm("LDA", Mem(CallArgBase + 4));
            EmitAsm("ORA", Mem(CallArgBase + 5));
            EmitAsm("BNE", Rel(mloop));
            _assembly.Add(Expr.Make(Tag.Label, mdone));
            EmitAsm("RTS");

            // Clear the high count byte for the small-fill wrapper.
            EmitHelperStart("__memset_small");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 4));
            EmitAsm("JMP", Abs("__memset"));

            // Advance the destination pointer while consuming the word count in the shared argument area.
            EmitHelperStart("__memset");
            string sloop = NewGeneratedLabel("memset_loop");
            string sdone = NewGeneratedLabel("memset_done");
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("ORA", Mem(CallArgBase + 4));
            EmitAsm("BEQ", Rel(sdone));
            _assembly.Add(Expr.Make(Tag.Label, sloop));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", IndY(CallArgBase));
            EmitAsm("INC", Mem(CallArgBase));
            string sd1 = NewGeneratedLabel("memset_dst_page_ok");
            EmitAsm("BNE", Rel(sd1));
            EmitAsm("INC", Mem(CallArgBase + 1));
            _assembly.Add(Expr.Make(Tag.Label, sd1));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            string slononzero = NewGeneratedLabel("memset_lenlo_nonzero");
            EmitAsm("BNE", Rel(slononzero));
            EmitAsm("DEC", Mem(CallArgBase + 4));
            _assembly.Add(Expr.Make(Tag.Label, slononzero));
            EmitAsm("DEC", Mem(CallArgBase + 3));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("ORA", Mem(CallArgBase + 4));
            EmitAsm("BNE", Rel(sloop));
            _assembly.Add(Expr.Make(Tag.Label, sdone));
            EmitAsm("RTS");
        }

void EmitFixedMemcpy(Expr dstExpr, Expr srcExpr, int len, FunctionContext ctx)
        {
            int[] ptr = AcquireTemps(4);
            try
            {
                EmitLoadValue(dstExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[0]));
                EmitAsm("STX", Mem(ptr[1]));
                EmitLoadValue(srcExpr, ctx, 2);
                EmitAsm("STA", Mem(ptr[2]));
                EmitAsm("STX", Mem(ptr[3]));
                for (int i = 0; i < len; i++)
                {
                    EmitAsm("LDY", Imm(i));
                    EmitAsm("LDA", IndY(ptr[2]));
                    EmitAsm("STA", IndY(ptr[0]));
                }
            }
            finally { ReleaseTemps(ptr); }
        }

// kitaqfc/kitaqfc/Lowerer.cs:2128
if (expr.MatchAny(Tag.Call, out callFunc, out callArgs))
        {
            string knownCallName;
            if (callFunc != null && callFunc.Match(Tag.Name, out knownCallName) &&
                knownCallName == "__cgb_is_cgb" &&
                callArgs != null && callArgs.Length == 0 &&
                // A resolved target configuration can replace the zero-argument CGB query with a literal.
                Program.TryGetKnownCgbRuntimeValue(out int knownCgbValue))
            {
                return Expr.Make(Tag.Integer, knownCgbValue).WithSource(expr.Source);
            }

            Expr newFunc = LowerExpr(ctx, callFunc, false, prefix);

            // Optimization (post-A3): when we must spill a non-atomic argument into a temp,
            // prefer a u8 temp if the *parameter type* is u8-like.
            // This preserves semantics (implicit truncation to u8) while avoiding needless
            // u16 temporaries created by integer promotions.
            CType[] paramTypes = null;
            string __fname = null;
            if (newFunc.Match(Tag.Name, out __fname))
            {
                paramTypes = ctx.FindFuncParams(__fname);
                if (paramTypes == null)
                {
                    CType fnTypeFromName;
                    if (TryGetCallableFunctionType(ctx.FindTypeOfName(__fname), out fnTypeFromName))
                        paramTypes = fnTypeFromName.ParamTypes;
                }
            }
            else
            {
                CType fnTypeFromExpr;
                if (TryGetCallableFunctionType(InferType(ctx, newFunc), out fnTypeFromExpr))
                    paramTypes = fnTypeFromExpr.ParamTypes;
            }

            Expr[] newArgs = new Expr[callArgs.Length];
            for (int i = 0; i < callArgs.Length; i++)
            {
                Expr a = LowerExpr(ctx, callArgs[i], allowExtract, prefix);

                bool preserveConstantArgIntrinsic = false;
                if (a.MatchAny(Tag.Call, out Expr argFunc, out Expr[] _argCallArgs) &&
                    argFunc.Match(Tag.Name, out string argFuncName))
                {
                    preserveConstantArgIntrinsic = (argFuncName == "__bankof" || argFuncName == "__cgb_is_cgb");
                }
                // Keep evaluable constants and special intrinsic/bank operands visible to code generation instead of spilling them.
                bool preserveCompileTimeConstantArg = ctx.Global.TryEvalConstInt(a, out _);
                bool preserveFarcallBankArg = (__fname == "__farcall" && i == 0);

                if (allowExtract && !preserveFarcallBankArg && !preserveConstantArgIntrinsic && !preserveCompileTimeConstantArg && !IsAtom(a))
                {
                    // If we know the callee's parameter type, use it to choose a smaller temp.
                    // Example: (u8)(row*32) passed to a u8 param should spill as u8, not u16.
                    CType spillAs = null;
                    if (paramTypes != null && i < paramTypes.Length)
                    {
                        CType pt = paramTypes[i];
                        if (IsU8Like(pt)) spillAs = CType.UInt8;
                    }
                    if (spillAs == null) spillAs = InferType(ctx, a);
                    if (!IsAggregateType(spillAs) && SizeOfType(spillAs) <= 2)
                        a = SpillToTemp(ctx, a, spillAs, prefix);
                }
                newArgs[i] = a;
            }

            // Lint: const discard for argument passing
            // Warn when passing a const-qualified pointer (or const array decay) to a non-const pointer parameter.
            // Suppress when the argument has an explicit cast, or inside __unsafe.
            if (!ctx.InUnsafe && paramTypes != null)
            {
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;
                    if (!IsPointerToNonConst(pt)) continue;
                    if (HasTopLevelCast(newArgs[i])) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at != null && (IsPointerToConst(at) || IsArrayOfConst(at)))
                    {
                        string fn = __fname ?? "<call>";
                        WarnConstDiscard(expr, $"argument {i} to '{fn}'");
                        break; // keep it quiet: one warning per call is enough
                    }
                }
            }

            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    FilePosition argPos = newArgs[i].Source;
                    if (string.IsNullOrEmpty(argPos.Filename) || argPos.Filename == "<unknown>")
                        argPos = expr.Source;
                    WarnImplicitNarrowingIfNeeded(ctx, newArgs[i], InferType(ctx, newArgs[i]), paramTypes[i], argPos,
                        "argument " + i + " to '" + fn + "'");
                }
            }

            // Lint: __enum_strict argument passing.
            if (paramTypes != null)
            {
                string fn = __fname ?? "<call>";
                for (int i = 0; i < newArgs.Length && i < paramTypes.Length; i++)
                {
                    CType pt = paramTypes[i];
                    if (pt == null) continue;

                    CType at = InferType(ctx, newArgs[i]);
                    if (at == null) continue;

                    if (HasTopLevelCast(newArgs[i])) continue;

                    if (IsStrictEnum(pt))
                    {
                        if (!IsSameEnum(pt, at))
                        {
                            Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                                "argument {0} to '{1}' expects __enum_strict {2}, got {3}; cast explicitly to silence",
                                i, fn, pt.Show(), at.Show());
                        }
                    }
                    else if (IsPlainInteger(pt) && IsStrictEnum(at))
                    {
                        Program.Warning(expr.Source, ErrorCode.EnumStrictMix,
                            "argument {0} to '{1}' passes __enum_strict {2} to integer parameter {3}; cast explicitly to silence",
                            i, fn, at.Show(), pt.Show());
                    }
                }
            }

            if (!ctx.InUnsafe)
                RestrictAliasLint(ctx, newFunc, newArgs, expr.Source);

            // __slice(ptr,len) helper: represent a "slice" (ptr+len) in the IR.
            // Semantics: evaluate both arguments, result type is the pointer/array (same as arg0).
            // Bounds checks are injected only with -Zcheck (see Program.CheckSliceBounds).
            // Note: keep the intrinsic name conservative to avoid collisions ("slice" is allowed only
            // when there is no declared function named "slice").
            if (newFunc.Match(Tag.Name, out string __sfname))
            {
                bool isSliceIntrinsic = (__sfname == "__slice") || (__sfname == "slice" && ctx.FindFuncParams("slice") == null);
                if (isSliceIntrinsic)
                {
                    if (newArgs.Length != 2)
                    {
                        Program.Error(expr.Source, ErrorCode.ParseError, "{0}: expected 2 arguments: __slice(ptr,len)", __sfname);
                    }
                    else
                    {
                        CType pty = InferType(ctx, newArgs[0]);
                        if (pty == null || !(pty.IsPointer || pty.IsArray))
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: first argument must be a pointer or array, got: {1}", __sfname, (pty == null ? "<unknown>" : pty.Show()));

                        CType lty = InferType(ctx, newArgs[1]);
                        if (lty == null || !lty.IsInteger)
                            Program.Error(expr.Source, ErrorCode.ExpectedType, "{0}: second argument must be an integer length, got: {1}", __sfname, (lty == null ? "<unknown>" : lty.Show()));
                    }

                    return Expr.Make(Tag.Slice, newArgs[0], newArgs[1]).WithSource(expr.Source);
                }
            }

            return MakeCall(newFunc, newArgs).WithSource(expr.Source);
        }

Déploie un flux de parties de sprite muni d’un terminateur dans des entrées consécutives du tampon miroir de la page 02. Chaque partie ajoute ses décalages X/Y d’un octet à la position de base et fournit sa tuile et ses attributs. Renvoie l’indice OAM suivant.

Syntaxe

u8 __metasprite_draw(u8 oam_index, u8 base_x, u8 base_y, const u8* metasprite);

Paramètres

oam_index

Indice du sprite, de 0 à 63, et non décalage en octets. Le calcul multiplie cet indice par quatre dans un curseur de 8 bits ; les valeurs hors plage sont ramenées modulo 64 et peuvent écraser une autre entrée. L’allocation n’est pas vérifiée.

base_x

Position horizontale en pixels, sous forme d’octet non signé ; ce n’est pas une coordonnée de tuile.

base_y

Octet Y de l’OAM. Pour placer le haut sous la ligne zéro, passez sa position moins un ; 239..255 sont hors des 240 lignes visibles.

metasprite

Pointeur vers des enregistrements lisibles de quatre octets : dx, dy, tile, attr. Un 0xFF à la position dx suivante termine le flux ; aucun octet supplémentaire n’est nécessaire. Les décalages s’ajoutent modulo 256 : 0xFE représente −2 et dy=0xFF peut représenter −1, mais dx=0xFF est réservé au terminateur. Le pointeur doit être valide dans la mémoire actuellement accessible.

Valeur renvoyée

Indice OAM suivant : (oam_index + parties_écrites) modulo 64. Il s’agit d’un curseur, pas du nombre de parties dessinées. Un flux vide renvoie oam_index modulo 64.

Conditions et limites

Ces opérations modifient la RAM CPU 0x0200–0x02FF, sans mettre immédiatement à jour l’OAM matérielle. Transférez la page complète avec __oam_dma. Elles ne tiennent à jour ni les indicateurs d’allocation, ni les tableaux de coordonnées, ni le compteur de la bibliothèque de sprites. Évitez qu’une interruption modifie ou transfère une page encore en préparation.

Le nombre de parties, le découpage à l’écran et la capacité ne sont pas vérifiés. Ajoutez un terminateur et limitez-vous à 64−oam_index parties. Les coordonnées sont ramenées modulo 256 ; après l’entrée 63, l’écriture reprend à l’entrée 0. Un flux vide ne modifie rien. Ce format diffère du tableau MetaSpritePart à nombre explicite utilisé par metasprite_draw dans la bibliothèque de sprites.

Exemple d’utilisation

fc_oam_next=__metasprite_draw(5,136,95,fc_oam_pair); // Returns 7 after two entries.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple réserve une ligne légendée à chaque opération. SET et MOVE montrent des flèches de 8×8 vers la droite en (144,16) et (144,32) ; TILE, un carré vert en (144,48) ; ATTR, la flèche retournée selon les deux axes en (144,64). HIDE en (144,80) et CLEAR en (144,112) doivent rester vides. META montre une paire en (136,96) et (144,96), la seconde flèche étant retournée horizontalement. NEXT 07 indique l’indice suivant après les entrées 5 et 6. Les bords sont rouges, la tige verte et les détails de la pointe bleus. La vérification compare 8 704 pixels par image et les octets OAM transférés ; le matériel physique n’a pas été testé.

TRANSFER montre une flèche en (144,128). Ce programme envoie directement la page 02 avec __oam_dma, y compris tous les champs préparés par les opérations individuelles sur les sprites.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\oam_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\sprite_example.chr -o .\out\oam_intrinsics.nes --no-cache --no-disasm

Expand dx,dy,tile,attr records into page-02 shadow OAM until dx=FF; return the next index.
Coordinates and the byte OAM cursor wrap; keep the terminated stream within the available slots.

EmitHelperStart("__metasprite_draw");
            // args: oam_index, base_x, base_y, metasprite_ptr16.
            // stream: dx, dy, tile, attr ... dx=$FF terminates. Returns next OAM index in A.
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("ASL");
            EmitAsm("ASL");
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address)); // dst byte offset
            string msLoop = NewGeneratedLabel("metasprite_loop");
            string msDone = NewGeneratedLabel("metasprite_done");
            _assembly.Add(Expr.Make(Tag.Label, msLoop));
            EmitAsm("LDY", Imm(0));
            EmitAsm("LDA", IndY(CallArgBase + 3));
            EmitAsm("CMP", Imm(0xFF));
            EmitAsm("BEQ", Rel(msDone));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address)); // dx
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("INY");
            EmitAsm("LDA", IndY(CallArgBase + 3));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(CallArgBase + 2));
            EmitAsm("STA", new AsmOperand(OamRamBase + 0, AddressMode.AbsoluteX));
            EmitAsm("INY");
            EmitAsm("LDA", IndY(CallArgBase + 3));
            EmitAsm("STA", new AsmOperand(OamRamBase + 1, AddressMode.AbsoluteX));
            EmitAsm("INY");
            EmitAsm("LDA", IndY(CallArgBase + 3));
            EmitAsm("STA", new AsmOperand(OamRamBase + 2, AddressMode.AbsoluteX));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(CallArgBase + 1));
            EmitAsm("STA", new AsmOperand(OamRamBase + 3, AddressMode.AbsoluteX));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(4));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(4));
            EmitAsm("STA", Mem(CallArgBase + 3));
            // Propagate stream-pointer page carry after consuming the complete four-byte record.
            string msPtrOk = NewGeneratedLabel("metasprite_ptr_ok");
            EmitAsm("BCC", Rel(msPtrOk));
            EmitAsm("INC", Mem(CallArgBase + 4));
            _assembly.Add(Expr.Make(Tag.Label, msPtrOk));
            EmitAsm("JMP", Abs(msLoop));
            _assembly.Add(Expr.Make(Tag.Label, msDone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LSR");
            EmitAsm("LSR");
            EmitAsm("RTS");

Lit le signal numérique du microphone de la seconde manette Famicom dans le bit 2 de $4016. La routine lit le registre une fois, applique le masque 0x04 et normalise à 0 ou 1 sans inversion. Elle ne verrouille pas les états des manettes, n’enregistre pas de son, ne mesure pas le volume et ne reconnaît pas la parole.

Syntaxe

u8 __mic_read2p(void);

Valeur renvoyée

Exactement 1 si $4016 & 0x04 est non nul, sinon 0. Il s’agit du niveau numérique échantillonné, pas d’un masque de boutons, d’une amplitude, d’une fréquence ou d’un nombre de mots prononcés.

Conditions et limites

Bien que le microphone appartienne à la manette 2, cette routine accède à $4016, pas à $4017. Une lecture du registre peut aussi faire avancer le flux série de la manette lorsque le strobe est bas ; n’insérez donc pas de lecture du microphone dans une autre boucle de lecture de huit bits. Aucun historique d’entrée mémorisé n’est mis à jour.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Exemple d’utilisation

mic_direct=__mic_read2p(); // A separate sample of the same digital signal.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare l’entrée ordinaire D0, l’extension D1 et le niveau numérique du microphone. Maintenez A sur la manette 1 et B sur la manette 2 jusqu’à la capture. NORMAL P1 et NORMAL P2 affichent 001 et 002. Dans l’exécution KUROSAKI fournie, D1 PORT 1, D1 PORT 2, EXP ALIAS 1, EXP ALIAS 2, MIC LEVEL et MIC DIRECT affichent 000, car ces lignes ne sont pas émulées. Les valeurs restent ensuite fixes. Avec des périphériques adaptés et leurs lignes implémentées, les valeurs dépendent des entrées réelles ; interprétez-les selon les bits décrits ci-dessus au lieu d’attendre ces zéros.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\expansion_input.c -I .\kitaq-docs\samples -I .\kitaqfc\lib -o .\out\expansion_input.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Alias the same normalized microphone input bit as __joypad2p_voice.

Envoie un octet d’horloge F8. L’appelant programme les impulsions répétées.

Syntaxe

void __midi_clock(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Transmit the single realtime byte F8 synchronously; this does not schedule future ticks.

case "__midi_clock": if (!Need(0)) return true; EmitAsm("LDA", Imm(0xF8)); EmitAsm("JSR", Abs("__kq_midi_out_a")); return true;

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Envoie un octet temps réel Continue FB sans agir sur le pilote musical interne.

Syntaxe

void __midi_continue(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Transmit realtime Continue (FB) through the serial adapter path.

case "__midi_continue": if (!Need(0)) return true; EmitAsm("LDA", Imm(0xFB)); EmitAsm("JSR", Abs("__kq_midi_out_a")); return true;

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Envoie un changement de contrôleur : 0xB0 | (ch & 0x0F), numéro de contrôleur, valeur.

Syntaxe

void __midi_control_change(u8 ch, u8 cc, u8 value);

Paramètres

ch

Canal MIDI de 0 à 15 ; le demi-octet bas entre dans l’octet d’état. Zéro correspond au canal MIDI affiché 1.

cc

Numéro de contrôleur de 0 à 127 ; 7 correspond au volume du canal.

value

Valeur de contrôleur de 0 à 127 ; les bits supérieurs ne sont pas effacés automatiquement.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Send B0|(ch&0F), controller and value; both data arguments must be valid 7-bit values.

case "__midi_control_change": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1}, funcName);

EmitHelperStart("__midi_control_change");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("AND", Imm(0x0F));
            EmitAsm("ORA", Imm(0xB0));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Attend une entrée de réception basse, puis échantillonne huit bits à intervalles temporisés.

Syntaxe

u8 __midi_in_byte(void);

Valeur renvoyée

Renvoie le u8 reçu. Aucun délai d’expiration, contrôle de trame ni tampon de réception. Une entrée maintenue haute bloque indéfiniment ; maintenue basse, elle donne zéro.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Block for a low start signal and sample eight bits. No timeout, framing check or receive buffer is provided.

case "__midi_in_byte": if (!Need(0)) return true; EmitAsm("JSR", Abs("__midi_in_byte")); return true;
                // Pack MIDI message fields as bytes; real-time commands below load their fixed status byte directly.

EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Envoie note-off en trois octets : 0x80 | (ch & 0x0F), note, velocity.

Syntaxe

void __midi_note_off(u8 ch, u8 note, u8 velocity);

Paramètres

ch

Canal MIDI de 0 à 15 ; le demi-octet bas entre dans l’octet d’état. Zéro correspond au canal MIDI affiché 1.

note

Note MIDI de 0 à 127 ; 69 est A4. Aucun masque sur sept bits n’est appliqué : l’appelant respecte la plage.

velocity

Vélocité de 0 à 127 ; aucun masquage automatique sur sept bits.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Send 80|(ch&0F), note and velocity through the same synchronous serial path.

case "__midi_note_off": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1}, funcName);

EmitHelperStart("__midi_note_off");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("AND", Imm(0x0F));
            EmitAsm("ORA", Imm(0x80));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Envoie note-on en trois octets : 0x90 | (ch & 0x0F), note, velocity.

Syntaxe

void __midi_note_on(u8 ch, u8 note, u8 velocity);

Paramètres

ch

Canal MIDI de 0 à 15 ; le demi-octet bas entre dans l’octet d’état. Zéro correspond au canal MIDI affiché 1.

note

Note MIDI de 0 à 127 ; 69 est A4. Aucun masque sur sept bits n’est appliqué : l’appelant respecte la plage.

velocity

Vélocité de 0 à 127 ; aucun masquage automatique sur sept bits.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Send 90|(ch&0F), note and velocity. Supply 7-bit data bytes; they are not masked by this helper.

case "__midi_note_on": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1}, funcName);

EmitHelperStart("__midi_note_on");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("AND", Imm(0x0F));
            EmitAsm("ORA", Imm(0x90));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Transmet synchronement un octet 8N1 : début bas, huit bits de données du moins au plus significatif, arrêt haut.

Syntaxe

void __midi_out_byte(u8 byte);

Paramètres

byte

Octet brut de 0 à 255, qu’il s’agisse d’un état ou de données.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Send start-low, eight least-significant-first bits and stop-high in 57-cycle
NTSC bit cells (about 31400 bps). Stop DMC DMA and mask IRQ/NMI during transfers;
PAL timing and electrical adapter compatibility are not established here.

case "__midi_out_byte": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1}, funcName);

EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Envoie un changement de programme : 0xC0 | (ch & 0x0F), puis le numéro de programme.

Syntaxe

void __midi_program_change(u8 ch, u8 program);

Paramètres

ch

Canal MIDI de 0 à 15 ; le demi-octet bas entre dans l’octet d’état. Zéro correspond au canal MIDI affiché 1.

program

Programme de 0 à 127 ; l’affectation des instruments dépend du récepteur.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Send C0|(ch&0F) followed by the caller-supplied 7-bit program value.

case "__midi_program_change": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1}, funcName);
                // Real-time MIDI commands send a single status byte through the common output routine.

EmitHelperStart("__midi_program_change");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("AND", Imm(0x0F));
            EmitAsm("ORA", Imm(0xC0));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Envoie un octet temps réel Start FA sans changer les pointeurs musicaux du jeu.

Syntaxe

void __midi_start(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Transmit realtime Start (FA) through the serial adapter path.

case "__midi_start": if (!Need(0)) return true; EmitAsm("LDA", Imm(0xFA)); EmitAsm("JSR", Abs("__kq_midi_out_a")); return true;

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Envoie un octet temps réel Stop FC. Cela ne coupe directement ni l’APU ni les notes déjà envoyées.

Syntaxe

void __midi_stop(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Nécessite un circuit externe reliant $4016 D0 à TX et $4017 D4 à RX. Une manette standard ne fournit pas MIDI, et ces appels ne jouent pas l’APU interne. Arrêtez DMC/DMA et masquez NMI et IRQ pendant les transferts ; évitez les accès concurrents aux ports et à la zone de travail partagée. Les 57 cycles par bit NTSC donnent environ 31 400 bit/s, soit +0,5 % par rapport à 31 250. Le minutage PAL et les échanges avec un adaptateur physique ne sont pas vérifiés.

Exemple d’utilisation

// Controller-port byte encoding. This does not synthesize sound inside the FC.
#define SOUND_PORT_ONLY
#include "fc_sound_example.h"
void main(void) {
    sound_begin("MIDI PORT BYTES");
    // sound_begin has disabled DMC DMA and all internal APU voices. A compatible external circuit is required.
    // Stop NMI and mask IRQ so neither can split a software-timed serial frame.
    __ppu_ctrl_set(0); __irq_disable();
    __midi_out_byte(0x7E);
    __midi_program_change(2,5);
    __midi_control_change(2,7,100);
    __midi_note_on(2,69,96);
    __midi_note_off(2,69,0);
    __midi_clock(); __midi_start(); __midi_continue(); __midi_stop();
    // The emulator's unconnected input bit is low. Reading returns zero here.
    // A real input held high would block waiting for its start bit, without timeout.
    sound_result[0]=__midi_in_byte();
    sound_result[1]=1;
    __ppu_ctrl_set(0x80); __irq_enable();
    sound_end();
}

Résultat attendu

L’écran affiche EXTERNAL PORT DATA et aucune voix interne ne sonne. Les octets transmis en hexadécimal sont 7E; C2 05; B2 07 64; 92 45 60; 82 45 00; F8 FA FB FC. Le contrôle exige des cellules de transmission NTSC de 57 cycles et des lectures espacées de 57 cycles. Le 00 reçu vient de l’entrée non connectée de l’émulateur et ne prouve pas une communication externe.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_midi.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-midi.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Transmit realtime Stop (FC) through the serial adapter path.

case "__midi_stop": if (!Need(0)) return true; EmitAsm("LDA", Imm(0xFC)); EmitAsm("JSR", Abs("__kq_midi_out_a")); return true;
                // Sprite helpers modify the runtime OAM representation; DMA remains a separate operation.

EmitHelperStart("__kq_midi_out_a");
            bool midiScratchInZeroPage = _runtimeIntrinsicTmp0Address <= 0xFF;
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(0x4016));
            // Unroll so neither branch cost nor payload bits change the baud.
            // Each data edge: 44 NOP cycles + LSR zp (5) + LDA/ADC (4) + STA (4).
            for (int bit = 0; bit < 8; bit++)
            {
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
                EmitAsm("LSR", Mem(_runtimeIntrinsicTmp0Address));
                EmitAsm("LDA", Imm(0));
                EmitAsm("ADC", Imm(0));
                EmitAsm("STA", Mem(0x4016));
            }
            // 51 delay cycles plus LDA/STA (6) place the stop bit 57 cycles later.
            for (int delay = 0; delay < 24; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(0x4016));
            EmitMidiBitDelay(); // Hold stop high for at least one full bit cell.
            EmitAsm("RTS");

            EmitHelperStart("__midi_out_byte");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__kq_midi_out_a"));
            EmitAsm("RTS");

            // Poll in nine-cycle steps, then sample near data-bit centers.
            // IRQ/NMI masking belongs to the caller; no timeout/framing status is returned.
            EmitHelperStart("__midi_in_byte");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string waitStart = NewGeneratedLabel("midi_wait_start");
            _assembly.Add(Expr.Make(Tag.Label, waitStart));
            EmitAsm("LDA", Mem(0x4017));
            EmitAsm("AND", Imm(0x10));
            EmitAsm("BNE", Rel(waitStart));
            // 81 cycles from the start-detect read to the first data read.
            // Polling uncertainty is at most nine cycles within a 57-cycle cell.
            for (int delay = 0; delay < 35; delay++) EmitAsm("NOP");
            EmitAsm("BIT", Mem(CallArgBase));
            for (int bit = 0; bit < 8; bit++)
            {
                EmitAsm("LDA", Mem(0x4017));
                EmitAsm("AND", Imm(0x10));
                EmitAsm("CMP", Imm(0x10));
                EmitAsm("ROR", Mem(_runtimeIntrinsicTmp0Address));
                for (int delay = 0; delay < (midiScratchInZeroPage ? 22 : 20); delay++) EmitAsm("NOP");
                if (!midiScratchInZeroPage) EmitAsm("BIT", Mem(CallArgBase));
            }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("RTS");

            // Compose the channelized note-on status, then send note and velocity arguments.

Associe les quatre régions logiques de tables de noms aux deux pages de RAM écran de la console, pour organiser le défilement ou choisir une page d’écran unique.

Syntaxe

void __mirroring_set(u8 mode);

Paramètres

mode

Les numéros de mode varient selon la carte. MMC1/SUROM : 0=écran unique bas, 1=écran unique haut, 2=vertical, 3=horizontal. MMC3 : 0=vertical, 1=horizontal. MMC5 : 0=horizontal, 1=vertical, 2=écran unique bas, 3=écran unique haut. AxROM : 0=écran unique bas, 1=écran unique haut. FME7 : 0=vertical, 1=horizontal, 2=écran unique bas, 3=écran unique haut. MMC3/AxROM utilisent le bit de poids faible ; les autres, les deux bits de poids faible.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les déclarations des intrinsèques sont dans intrinsics.h. Incluez nes_game.h pour les macros nes_mapper_irq_*. Choisissez la carte à la compilation avec --mapper.

Le mirroring vertical fait correspondre les quatre régions à A B A B ; l’horizontal donne A A B B. L’écran unique bas donne A A A A, le haut B B B B. Cela change le mappage mémoire, sans retourner ni copier les graphismes du fond. Les cartes non prises en charge, dont NROM à mirroring fixe, sont refusées à la compilation.

MMC1 écrit le contrôle $0C|mode, sélectionnant une fenêtre PRG haute fixe de 16 Kio et le mode CHR 8 Kio. SUROM met aussi à jour sa copie logicielle du contrôle. AxROM change le bit d’écran en conservant la banque PRG suivie à l’exécution. Si vous écrivez aussi directement dans les registres du mapper, maintenez leur cohérence avec l’état de banque du programme.

Pour MMC5, l’API écrit $50/$44/$00/$55 dans $5105. Ces dispositions n’utilisent que les deux pages CIRAM de la console. ExRAM et le mode de remplissage sont hors de cette API. KUROSAKI prend en charge les seize dispositions utilisant uniquement la CIRAM ; le rendu MMC5 ExRAM et de remplissage n’est pas pris en charge.

Remplacez --mapper=mmc3 dans l’exemple par mmc1, mmc5, axrom ou fme7 pour examiner chaque carte. L’exemple initialise les banques CHR de police MMC5/FME7 via leurs registres de carte.

Exemple d’utilisation

k=1;
    for (i=0;i<4;i++) {
        __mirroring_set(i);
        for (j=0;j<4;j++) { mirror_result[k]=mirror_read(0x2000+(u16)j*1024); k++; }
    }

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

La leçon écrit 17 dans la page RAM physique basse et 34 dans la page haute, puis lit les quatre régions logiques. A désigne la page basse, B la haute. Les régions portant la même lettre partagent la RAM : une écriture dans l’une est visible dans les autres. Les colonnes sont $2000, $2400, $2800 et $2C00 ; les lignes sont les modes 0 à 3. Le texte s’affiche après la relecture.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\mapper_mirroring.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\mapper_mirroring.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Emit the selected mapper mirroring operation; available modes and writable control depend on the board.

Calcule une multiplication non signée.

Syntaxe

u16 __mul16x8(u16 a, u8 b);

Paramètres

a

Mot non signé de 0 à 65535.

b

Coefficient non signé de 0 à 255.

Valeur renvoyée

Renvoie les 16 bits de poids faible de a*b.

Conditions et limites

Sur FC, les fonctions nommées q8_8/q1_7 utilisent les produits entiers bruts, sans décalage de mise à l’échelle fixe. Les fonctions Q1.7 sont des alias des opérations signées correspondantes. L’appelant gère les unités ; les résultats signés sont renvoyés comme motifs de bits u16.

Exemple d’utilisation

// Compare literal coefficients with values read from RAM.
result[2]=__mul16x8(513,127);
v0=513;v1=127;
result[3]=__mul16x8(v0,v1);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Comparez les entrées littérales aux valeurs en RAM. Les résultats représentatifs sont affichés sur 16 bits non signés ; les négatifs utilisent le complément à deux. Le GB remet à l’échelle les produits à virgule fixe, tandis que le FC renvoie des produits entiers : des entrées identiques ne donnent donc pas nécessairement les mêmes résultats.

L’extrait stocke les valeurs suivantes sur 16 bits : result[2]=65151, result[3]=65151. Chaque calcul avec une entrée littérale correspond à son équivalent avec une entrée en RAM. L’écran affiche des valeurs représentatives ; le tableau result conserve tous les résultats.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch3_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return the low word of the unsigned product; overflow wraps without saturation.

case "__mul16x8": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2,1}, funcName);

void EmitHelperMath()
        {
            // Consume eight multiplier bits and accumulate the low product word in shared temporaries, returning A/X.
            EmitHelperStart("__mul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDX", Imm(8));
            string loop = NewGeneratedLabel("mul16x8_loop");
            string skip = NewGeneratedLabel("mul16x8_skip_add");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LSR", Mem(CallArgBase + 2));
            EmitAsm("BCC", Rel(skip));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("ADC", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, skip));
            EmitAsm("ASL", Mem(CallArgBase));
            EmitAsm("ROL", Mem(CallArgBase + 1));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(loop));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            // Zero-extend the byte multiplicand, reuse word multiplication and return its high byte.
            EmitHelperStart("__mul8x8_hi");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("TXA");
            EmitAsm("RTS");

            // Convert signed operands to magnitudes, multiply, then restore the product sign modulo 65536.
            EmitHelperStart("__smul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            string aPos = NewGeneratedLabel("smul_a_positive");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(aPos));
            EmitAsm("LDA", Mem(CallArgBase)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("LDA", Mem(CallArgBase + 1)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, aPos));
            string bPos = NewGeneratedLabel("smul_b_positive");
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(bPos));
            EmitAsm("LDA", Mem(CallArgBase + 2)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, bPos));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STX", Mem(_runtimeIntrinsicTmp1Address));
            string sdone = NewGeneratedLabel("smul_done");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("BEQ", Rel(sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            EmitMacHelper("__mac16", "__mul16x8");
            EmitMacHelper("__smac16", "__smul16x8");
            EmitDot2Helper("__dot2_q8_8", "__mul16x8");
            EmitDot3Helper("__dot3_q8_8", "__mul16x8");
            EmitDot2Helper("__sdot2_q8_8", "__smul16x8");
            EmitDot3Helper("__sdot3_q8_8", "__smul16x8");
        }

Multiplie deux octets non signés et renvoie l’octet de poids fort.

Syntaxe

u8 __mul8x8_hi(u8 a, u8 b);

Paramètres

a

Octet non signé de 0 à 255.

b

Octet non signé de 0 à 255.

Valeur renvoyée

floor(a*b/256), dans l’intervalle 0..254.

Exemple d’utilisation

// Compare literal coefficients with values read from RAM.
result[0]=__mul8x8_hi(255,255);
v0=255;v1=255;
result[1]=__mul8x8_hi(v0,v1);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Comparez les entrées littérales aux valeurs en RAM. Les résultats représentatifs sont affichés sur 16 bits non signés ; les négatifs utilisent le complément à deux. Le GB remet à l’échelle les produits à virgule fixe, tandis que le FC renvoie des produits entiers : des entrées identiques ne donnent donc pas nécessairement les mêmes résultats.

L’extrait stocke les valeurs suivantes sur 16 bits : result[0]=254, result[1]=254. Chaque calcul avec une entrée littérale correspond à son équivalent avec une entrée en RAM. L’écran affiche des valeurs représentatives ; le tableau result conserve tous les résultats.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch3_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return the high byte of the unsigned 8-by-8 product, equivalent to floor(a*b/256).

case "__mul8x8_hi": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1}, funcName);

void EmitHelperMath()
        {
            // Consume eight multiplier bits and accumulate the low product word in shared temporaries, returning A/X.
            EmitHelperStart("__mul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDX", Imm(8));
            string loop = NewGeneratedLabel("mul16x8_loop");
            string skip = NewGeneratedLabel("mul16x8_skip_add");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LSR", Mem(CallArgBase + 2));
            EmitAsm("BCC", Rel(skip));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("ADC", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, skip));
            EmitAsm("ASL", Mem(CallArgBase));
            EmitAsm("ROL", Mem(CallArgBase + 1));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(loop));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            // Zero-extend the byte multiplicand, reuse word multiplication and return its high byte.
            EmitHelperStart("__mul8x8_hi");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("TXA");
            EmitAsm("RTS");

            // Convert signed operands to magnitudes, multiply, then restore the product sign modulo 65536.
            EmitHelperStart("__smul16x8");
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            string aPos = NewGeneratedLabel("smul_a_positive");
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(aPos));
            EmitAsm("LDA", Mem(CallArgBase)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("LDA", Mem(CallArgBase + 1)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(CallArgBase + 1));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, aPos));
            string bPos = NewGeneratedLabel("smul_b_positive");
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("AND", Imm(0x80));
            EmitAsm("BEQ", Rel(bPos));
            EmitAsm("LDA", Mem(CallArgBase + 2)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(CallArgBase + 2));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("EOR", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            _assembly.Add(Expr.Make(Tag.Label, bPos));
            EmitAsm("JSR", Abs("__mul16x8"));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STX", Mem(_runtimeIntrinsicTmp1Address));
            string sdone = NewGeneratedLabel("smul_done");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("BEQ", Rel(sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("CLC"); EmitAsm("ADC", Imm(1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("EOR", Imm(0xFF)); EmitAsm("ADC", Imm(0)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, sdone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDX", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("RTS");

            EmitMacHelper("__mac16", "__mul16x8");
            EmitMacHelper("__smac16", "__smul16x8");
            EmitDot2Helper("__dot2_q8_8", "__mul16x8");
            EmitDot3Helper("__dot3_q8_8", "__mul16x8");
            EmitDot2Helper("__sdot2_q8_8", "__smul16x8");
            EmitDot3Helper("__sdot3_q8_8", "__smul16x8");
        }

Écrit directement un octet de tuile dans la table de noms 0, à 0x2000 + y*32 + x. Réinitialise le verrou avant de définir l’adresse. N’écrit ni graphisme de tuile ni attribut de palette et ne limite pas les coordonnées.

Syntaxe

void __nametable_put(u8 x, u8 y, u8 tile);

Paramètres

x / y

Coordonnées de tuiles, pas de pixels. Gardez x dans 0..31 et y dans 0..29 pour la carte visible de 32×30 tuiles ; chaque tuile couvre 8×8 pixels. Les arguments d’un octet ne sont pas bornés automatiquement et peuvent écrire hors de la zone voulue.

tile

Numéro de tuile 0..255 dans la table de motifs de fond choisie par PPUCTRL. Sélectionne un graphisme CHR existant, pas une couleur de pixel ni un pointeur source.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__nametable_put(2,12,1); // Blue solid marker at (16,96).

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Write one tile directly at 2000+y*32+x; use x<32, y<30 for visible nametable cells.

case "__nametable_put": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1}, funcName);

void EmitHelperNametablePut()
        {
            EmitHelperStart("__nametable_put");
            // args: x, y, tile. PPU address = $2000 + y * 32 + x.
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            for (int i = 0; i < 5; i++) { EmitAsm("ASL", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("ROL", Mem(_runtimeIntrinsicTmp1Address)); }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("ADC", Imm(0x20));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(0x2002));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(0x2007));
            EmitAsm("RTS");
        }

Sélectionne la table logique nt & 3 et écrit une tuile à 0x2000 + (nt & 3)*0x400 + y*32 + x. Réinitialise le verrou avant la paire d’adresse. Le mirroring de la cartouche peut faire correspondre plusieurs numéros logiques à la même mémoire physique.

Syntaxe

void __nametable_put_nt(u8 nt, u8 x, u8 y, u8 tile);

Paramètres

nt

Sélecteur de table logique. Seuls les deux bits faibles sont utilisés (nt & 3) : 4 choisit la table 0 et 7 la table 3. N’alloue pas de mémoire indépendante et ne change pas le mirroring du mapper.

x / y

Coordonnées de tuiles, pas de pixels. Gardez x dans 0..31 et y dans 0..29 pour la carte visible de 32×30 tuiles ; chaque tuile couvre 8×8 pixels. Les arguments d’un octet ne sont pas bornés automatiquement et peuvent écrire hors de la zone voulue.

tile

Numéro de tuile 0..255 dans la table de motifs de fond choisie par PPUCTRL. Sélectionne un graphisme CHR existant, pas une couleur de pixel ni un pointeur source.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__nametable_put_nt(4,10,12,2); // Red left-half marker at (80,96), table 0.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Write one tile in nametable nt&3. Mirroring can alias logical nametables; coordinates are unchecked.

case "__nametable_put_nt": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1,1}, funcName);

void EmitHelperNametablePutNt()
        {
            EmitHelperStart("__nametable_put_nt");
            // args: nt,x,y,tile. PPU address = $2000 + nt*$400 + y*32 + x.
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("AND", Imm(3));
            EmitAsm("ASL");
            EmitAsm("ASL");
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(0x20));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            for (int i = 0; i < 5; i++) { EmitAsm("ASL", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("ROL", Mem(_runtimeIntrinsicTmp1Address)); }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("CLC");
            EmitAsm("ADC", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("ADC", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(0x2002));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Mem(CallArgBase + 3));
            EmitAsm("STA", Mem(0x2007));
            EmitAsm("RTS");
        }

Remplit un rectangle de w par h tuiles dans la table de noms 0 à partir de (x,y). Réinitialise le verrou et l’adresse à chaque ligne, écrit w copies de tile, puis avance le début de ligne suivant de 32 octets. Ne modifie pas les attributs de palette.

Syntaxe

void __nametable_rect(u8 x, u8 y, u8 w, u8 h, u8 tile);

Paramètres

x / y

Coordonnées de tuiles, pas de pixels. Gardez x dans 0..31 et y dans 0..29 pour la carte visible de 32×30 tuiles ; chaque tuile couvre 8×8 pixels. Les arguments d’un octet ne sont pas bornés automatiquement et peuvent écrire hors de la zone voulue.

w / h

Largeur et hauteur en tuiles, chacune sur un octet non signé. Respectez x+w<=32 et y+h<=30. Une hauteur nulle n’accède pas à la PPU. Une largeur nulle n’écrit aucune tuile, mais réinitialise le verrou et définit les h adresses de ligne. Utilisez l’incrément PPU 1 pour les lignes horizontales.

tile

Numéro de tuile 0..255 dans la table de motifs de fond choisie par PPUCTRL. Sélectionne un graphisme CHR existant, pas une couleur de pixel ni un pointeur source.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__nametable_rect(2,6,8,4,1); // Solid green rectangle at (16,48), 64x32 pixels.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Fill rows of nametable zero directly, advancing each row start by 32 bytes.
Keep the rectangle in bounds and use PPU increment one; this does not enqueue or clip.

case "__nametable_rect": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1,1,1}, funcName);

void EmitHelperNametableRect()
        {
            EmitHelperStart("__nametable_rect");
            // args: x,y,w,h,tile; writes tile-filled rectangle to nametable 0.
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            for (int i = 0; i < 5; i++) { EmitAsm("ASL", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("ROL", Mem(_runtimeIntrinsicTmp1Address)); }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("CLC"); EmitAsm("ADC", Mem(CallArgBase)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("ADC", Imm(0x20)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(CallArgBase + 3)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            string rowLoop = NewGeneratedLabel("nt_rect_row");
            string done = NewGeneratedLabel("nt_rect_done");
            _assembly.Add(Expr.Make(Tag.Label, rowLoop));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("BEQ", Rel(done));
            EmitAsm("LDA", Mem(0x2002)); EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("STA", Mem(0x2006)); EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDY", Imm(0));
            string colLoop = NewGeneratedLabel("nt_rect_col");
            string rowDone = NewGeneratedLabel("nt_rect_row_done");
            _assembly.Add(Expr.Make(Tag.Label, colLoop));
            EmitAsm("CPY", Mem(CallArgBase + 2)); EmitAsm("BEQ", Rel(rowDone));
            EmitAsm("LDA", Mem(CallArgBase + 4)); EmitAsm("STA", Mem(0x2007)); EmitAsm("INY"); EmitAsm("BNE", Rel(colLoop));
            _assembly.Add(Expr.Make(Tag.Label, rowDone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("CLC"); EmitAsm("ADC", Imm(32)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("BCC", Rel(rowLoop + "_nohi"));
            EmitAsm("INC", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, rowLoop + "_nohi"));
            EmitAsm("DEC", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("JMP", Abs(rowLoop));
            _assembly.Add(Expr.Make(Tag.Label, done));
            EmitAsm("RTS");
        }

Remplit w tuiles par ligne sur h lignes dans la table logique nt & 3. La première adresse est 0x2000 + (nt & 3)*0x400 + y*32 + x ; chaque début de ligne avance de 32 octets. Écrit uniquement les tuiles, sans attributs, découpage aux limites ni configuration du mirroring.

Syntaxe

void __nametable_rect_nt(u8 nt, u8 x, u8 y, u8 w, u8 h, u8 tile);

Paramètres

nt

Sélecteur de table logique. Seuls les deux bits faibles sont utilisés (nt & 3) : 4 choisit la table 0 et 7 la table 3. N’alloue pas de mémoire indépendante et ne change pas le mirroring du mapper.

x / y

Coordonnées de tuiles, pas de pixels. Gardez x dans 0..31 et y dans 0..29 pour la carte visible de 32×30 tuiles ; chaque tuile couvre 8×8 pixels. Les arguments d’un octet ne sont pas bornés automatiquement et peuvent écrire hors de la zone voulue.

w / h

Largeur et hauteur en tuiles, chacune sur un octet non signé. Respectez x+w<=32 et y+h<=30. Une hauteur nulle n’accède pas à la PPU. Une largeur nulle n’écrit aucune tuile, mais réinitialise le verrou et définit les h adresses de ligne. Utilisez l’incrément PPU 1 pour les lignes horizontales.

tile

Numéro de tuile 0..255 dans la table de motifs de fond choisie par PPUCTRL. Sélectionne un graphisme CHR existant, pas une couleur de pixel ni un pointeur source.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__nametable_rect_nt(4,18,6,8,4,3); // nt&3=0; red triangle tiles at (144,48).

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Fill a rectangle in nametable nt&3 with the same unchecked, direct-write row loop.

case "__nametable_rect_nt": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {1,1,1,1,1,1}, funcName);

void EmitHelperNametableRectNt()
        {
            EmitHelperStart("__nametable_rect_nt");
            // args: nt,x,y,w,h,tile.
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("AND", Imm(3));
            EmitAsm("ASL");
            EmitAsm("ASL");
            EmitAsm("CLC");
            EmitAsm("ADC", Imm(0x20));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("LDA", Mem(CallArgBase + 2));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            for (int i = 0; i < 5; i++) { EmitAsm("ASL", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("ROL", Mem(_runtimeIntrinsicTmp1Address)); }
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("CLC"); EmitAsm("ADC", Mem(CallArgBase + 1)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("ADC", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp1Address));
            EmitAsm("LDA", Mem(CallArgBase + 4)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp2Address));
            string rowLoop = NewGeneratedLabel("nt_rect_nt_row");
            string done = NewGeneratedLabel("nt_rect_nt_done");
            _assembly.Add(Expr.Make(Tag.Label, rowLoop));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp2Address)); EmitAsm("BEQ", Rel(done));
            EmitAsm("LDA", Mem(0x2002)); EmitAsm("LDA", Mem(_runtimeIntrinsicTmp1Address)); EmitAsm("STA", Mem(0x2006)); EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDY", Imm(0));
            string colLoop = NewGeneratedLabel("nt_rect_nt_col");
            string rowDone = NewGeneratedLabel("nt_rect_nt_row_done");
            _assembly.Add(Expr.Make(Tag.Label, colLoop));
            EmitAsm("CPY", Mem(CallArgBase + 3)); EmitAsm("BEQ", Rel(rowDone));
            EmitAsm("LDA", Mem(CallArgBase + 5)); EmitAsm("STA", Mem(0x2007)); EmitAsm("INY"); EmitAsm("BNE", Rel(colLoop));
            _assembly.Add(Expr.Make(Tag.Label, rowDone));
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address)); EmitAsm("CLC"); EmitAsm("ADC", Imm(32)); EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("BCC", Rel(rowLoop + "_nohi"));
            EmitAsm("INC", Mem(_runtimeIntrinsicTmp1Address));
            _assembly.Add(Expr.Make(Tag.Label, rowLoop + "_nohi"));
            EmitAsm("DEC", Mem(_runtimeIntrinsicTmp2Address));
            EmitAsm("JMP", Abs(rowLoop));
            _assembly.Add(Expr.Make(Tag.Label, done));
            EmitAsm("RTS");
        }

Désactive la génération de NMI par la PPU : efface le bit 7 de la copie de PPUCTRL du compilateur, puis l’écrit dans $2000. Les autres bits sont conservés. Le masque IRQ du processeur et le rendu ne sont pas modifiés.

Syntaxe

void __nmi_disable(void);

Valeur renvoyée

Aucune (void).

Conditions et limites

Ces fonctions utilisent la copie de PPUCTRL sans relire le matériel ; écrire directement dans $2000 ne la met pas à jour. Activer la NMI avec l’indicateur VBlank positionné peut la déclencher immédiatement. Désactiver sa génération par la PPU n’annule pas une requête déjà mémorisée par le processeur.

NESdev: NMI

NESdev : interruptions du CPU

Exemple d’utilisation

__nmi_disable();
before_count=__nmi_ready();
for(i=0;i<2000;i++)frozen=__nmi_ready();
frozen=(u8)(frozen-before_count); // No default-handler advances while off.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme distingue le masque IRQ du processeur du contrôle NMI de la PPU. En bleu sur fond noir doivent apparaître IRQ DISABLED I = 001, IRQ ENABLED I = 000, SAVED SECTION I = 001 et RESTORED I = 000. Chaque valeur représente le bit I extrait, pas l’octet d’état complet. FAILED CHECKS doit valoir 000.

Exécutez au moins 360 images pour terminer la démonstration des 256 attentes. NMI DELTA 3 WAITS doit valoir 003 même avec les IRQ masquées ; NMI DELTA 256 WAITS doit valoir 000, car le compteur sur un octet boucle. NMI OFF DELTA doit aussi valoir 000. Le programme utilise le gestionnaire par défaut sans runtime.c. Vingt et un contrôles d’état distincts couvrent notamment la restauration des indicateurs et des attentes observées sur une durée limitée avec NMI désactivée ou un gestionnaire personnalisé vide. KUROSAKI/NROM est vérifié, pas le matériel réel.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\interrupt_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\font.chr -o .\out\interrupt_intrinsics.nes --no-cache --no-disasm

Clear bit 7 in the PPUCTRL shadow and write it to hardware; CPU IRQ masking is separate.

case "__nmi_disable":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Mem(_runtimePpuCtrlShadowAddress)); EmitAsm("AND", Imm(0x7F)); EmitAsm("STA", Mem(_runtimePpuCtrlShadowAddress)); EmitAsm("STA", Mem(0x2000)); return true;

Active la NMI produite par la PPU : positionne le bit 7 de la copie de PPUCTRL conservée par le compilateur, puis écrit cette valeur dans $2000. Les autres bits de cette copie et le masque IRQ du processeur sont conservés. Le rendu du fond et des sprites n’est pas activé.

Syntaxe

void __nmi_enable(void);

Valeur renvoyée

Aucune (void).

Conditions et limites

Ces fonctions utilisent la copie de PPUCTRL sans relire le matériel ; écrire directement dans $2000 ne la met pas à jour. Activer la NMI avec l’indicateur VBlank positionné peut la déclencher immédiatement. Désactiver sa génération par la PPU n’annule pas une requête déjà mémorisée par le processeur.

NESdev: NMI

NESdev : interruptions du CPU

Exemple d’utilisation

__nmi_enable(); // Preserve the PPUCTRL shadow's other bits; CPU I stays set.
__nmi_wait(); // The default NMI handler still runs with IRQ masked.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme distingue le masque IRQ du processeur du contrôle NMI de la PPU. En bleu sur fond noir doivent apparaître IRQ DISABLED I = 001, IRQ ENABLED I = 000, SAVED SECTION I = 001 et RESTORED I = 000. Chaque valeur représente le bit I extrait, pas l’octet d’état complet. FAILED CHECKS doit valoir 000.

Exécutez au moins 360 images pour terminer la démonstration des 256 attentes. NMI DELTA 3 WAITS doit valoir 003 même avec les IRQ masquées ; NMI DELTA 256 WAITS doit valoir 000, car le compteur sur un octet boucle. NMI OFF DELTA doit aussi valoir 000. Le programme utilise le gestionnaire par défaut sans runtime.c. Vingt et un contrôles d’état distincts couvrent notamment la restauration des indicateurs et des attentes observées sur une durée limitée avec NMI désactivée ou un gestionnaire personnalisé vide. KUROSAKI/NROM est vérifié, pas le matériel réel.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\interrupt_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\font.chr -o .\out\interrupt_intrinsics.nes --no-cache --no-disasm

Set bit 7 in the PPUCTRL shadow and write it to hardware, preserving the other shadow bits.

case "__nmi_enable":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Mem(_runtimePpuCtrlShadowAddress)); EmitAsm("ORA", Imm(0x80)); EmitAsm("STA", Mem(_runtimePpuCtrlShadowAddress)); EmitAsm("STA", Mem(0x2000)); return true;

Lit le compteur NMI courant du compilateur sans attendre ni le remettre à zéro. Malgré le nom ready, le résultat est un compteur sur un octet, pas un indicateur booléen. Comparez-le à une valeur sauvegardée pour détecter une progression du gestionnaire NMI par défaut.

Syntaxe

u8 __nmi_ready(void);

Valeur renvoyée

Un octet non signé, de 0 à 255, incrémenté modulo 256 par le gestionnaire NMI par défaut. Zéro est valide. Après 256 incréments, la valeur courante rejoint la valeur sauvegardée ; des lectures espacées ne permettent pas de compter une durée arbitrairement longue.

Conditions et limites

Ce compteur appartient au gestionnaire NMI par défaut du compilateur. Définir __nes_nmi le remplace. runtime.c utilise ses propres nes_nmi_counter et nes_wait_nmi. Un gestionnaire personnalisé vide n’incrémente pas le compteur du compilateur et __nmi_wait ne revient pas. Activez la NMI et attendez hors de son gestionnaire.

NESdev: NMI

NESdev : interruptions du CPU

Exemple d’utilisation

before_count=__nmi_ready(); // A wrapping byte, not a Boolean ready flag.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme distingue le masque IRQ du processeur du contrôle NMI de la PPU. En bleu sur fond noir doivent apparaître IRQ DISABLED I = 001, IRQ ENABLED I = 000, SAVED SECTION I = 001 et RESTORED I = 000. Chaque valeur représente le bit I extrait, pas l’octet d’état complet. FAILED CHECKS doit valoir 000.

Exécutez au moins 360 images pour terminer la démonstration des 256 attentes. NMI DELTA 3 WAITS doit valoir 003 même avec les IRQ masquées ; NMI DELTA 256 WAITS doit valoir 000, car le compteur sur un octet boucle. NMI OFF DELTA doit aussi valoir 000. Le programme utilise le gestionnaire par défaut sans runtime.c. Vingt et un contrôles d’état distincts couvrent notamment la restauration des indicateurs et des attentes observées sur une durée limitée avec NMI désactivée ou un gestionnaire personnalisé vide. KUROSAKI/NROM est vérifié, pas le matériel réel.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\interrupt_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\font.chr -o .\out\interrupt_intrinsics.nes --no-cache --no-disasm

Return the current wrapping NMI counter byte, not a Boolean ready flag.

case "__nmi_ready": if (!Need(0)) return true; EmitAsm("LDA", Mem(_runtimeNmiCounterAddress)); return true;
                // Reset OAMADDR and transfer page 02; the page-selecting variant evaluates its own byte argument.

// The default NMI executes the queued VRAM work and increments the runtime frame counter before RTI.
            if (!_functions.ContainsKey("__nes_nmi"))
            {
                EmitPlacement(0, true);
                _assembly.Add(Expr.Make(Tag.Function, "__kq_nmi_default"));
                // NMI may interrupt argument evaluation, a pointer dispatch or an ordinary expression.
                // Preserve registers and every shared byte touched by the queue executor; RTI restores P.
                EmitAsm("PHA"); EmitAsm("TXA"); EmitAsm("PHA"); EmitAsm("TYA"); EmitAsm("PHA");
                int[] queueScratch = { CallArgBase, CallArgBase + 1, CallArgBase + 2,
                    _runtimeIntrinsicTmp0Address, _runtimeIntrinsicTmp1Address, _runtimeIntrinsicTmp2Address };
                foreach (int address in queueScratch) { EmitAsm("LDA", Mem(address)); EmitAsm("PHA"); }
                // The optional library hook preserves its own registers and uses no
                // compiler scratch. It consumes only RAM records and fixed ROM tables.
                if (_functions.ContainsKey("__nes_audio_vblank_tick"))
                    EmitAsm("JSR", Abs("__nes_audio_vblank_tick"));
                EmitAsm("JSR", Abs("__vramq_exec"));
                EmitAsm("INC", Mem(_runtimeNmiCounterAddress));
                foreach (int address in queueScratch.Reverse()) { EmitAsm("PLA"); EmitAsm("STA", Mem(address)); }
                EmitAsm("PLA"); EmitAsm("TAY"); EmitAsm("PLA"); EmitAsm("TAX"); EmitAsm("PLA");
                EmitAsm("RTI");
            }

Lit le compteur NMI du compilateur à l’entrée, puis attend dans une boucle qu’il change. Avec le gestionnaire par défaut, attend la fin d’une exécution ultérieure du gestionnaire, traitement de la file VRAM validée compris. N’active pas la NMI, ne valide pas les commandes et ne prévoit aucun délai maximal.

Syntaxe

void __nmi_wait(void);

Valeur renvoyée

Aucune (void).

Conditions et limites

Ce compteur appartient au gestionnaire NMI par défaut du compilateur. Définir __nes_nmi le remplace. runtime.c utilise ses propres nes_nmi_counter et nes_wait_nmi. Un gestionnaire personnalisé vide n’incrémente pas le compteur du compilateur et __nmi_wait ne revient pas. Activez la NMI et attendez hors de son gestionnaire.

NESdev: NMI

NESdev : interruptions du CPU

Exemple d’utilisation

__nmi_wait();__nmi_wait();__nmi_wait();
delta=(u8)(__nmi_ready()-before_count); // Three completed default NMIs.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme distingue le masque IRQ du processeur du contrôle NMI de la PPU. En bleu sur fond noir doivent apparaître IRQ DISABLED I = 001, IRQ ENABLED I = 000, SAVED SECTION I = 001 et RESTORED I = 000. Chaque valeur représente le bit I extrait, pas l’octet d’état complet. FAILED CHECKS doit valoir 000.

Exécutez au moins 360 images pour terminer la démonstration des 256 attentes. NMI DELTA 3 WAITS doit valoir 003 même avec les IRQ masquées ; NMI DELTA 256 WAITS doit valoir 000, car le compteur sur un octet boucle. NMI OFF DELTA doit aussi valoir 000. Le programme utilise le gestionnaire par défaut sans runtime.c. Vingt et un contrôles d’état distincts couvrent notamment la restauration des indicateurs et des attentes observées sur une durée limitée avec NMI désactivée ou un gestionnaire personnalisé vide. KUROSAKI/NROM est vérifié, pas le matériel réel.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\interrupt_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\font.chr -o .\out\interrupt_intrinsics.nes --no-cache --no-disasm

NMI / IRQ
Spin until the runtime NMI counter changes; the configured handler must advance it. No timeout is emitted.

case "__nmi_wait": if (!Need(0)) return true; EmitAsm("JSR", Abs("__nmi_wait")); return true;
                // Return the current NMI counter byte; callers decide how to compare it with their previous value.

void EmitHelperNmiWait()
        {
            EmitHelperStart("__nmi_wait");
            EmitAsm("LDA", Mem(_runtimeNmiCounterAddress));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            string loop = NewGeneratedLabel("nmi_wait_loop");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LDA", Mem(_runtimeNmiCounterAddress));
            EmitAsm("CMP", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("BEQ", Rel(loop));
            EmitAsm("RTS");
        }

// The default NMI executes the queued VRAM work and increments the runtime frame counter before RTI.
            if (!_functions.ContainsKey("__nes_nmi"))
            {
                EmitPlacement(0, true);
                _assembly.Add(Expr.Make(Tag.Function, "__kq_nmi_default"));
                // NMI may interrupt argument evaluation, a pointer dispatch or an ordinary expression.
                // Preserve registers and every shared byte touched by the queue executor; RTI restores P.
                EmitAsm("PHA"); EmitAsm("TXA"); EmitAsm("PHA"); EmitAsm("TYA"); EmitAsm("PHA");
                int[] queueScratch = { CallArgBase, CallArgBase + 1, CallArgBase + 2,
                    _runtimeIntrinsicTmp0Address, _runtimeIntrinsicTmp1Address, _runtimeIntrinsicTmp2Address };
                foreach (int address in queueScratch) { EmitAsm("LDA", Mem(address)); EmitAsm("PHA"); }
                // The optional library hook preserves its own registers and uses no
                // compiler scratch. It consumes only RAM records and fixed ROM tables.
                if (_functions.ContainsKey("__nes_audio_vblank_tick"))
                    EmitAsm("JSR", Abs("__nes_audio_vblank_tick"));
                EmitAsm("JSR", Abs("__vramq_exec"));
                EmitAsm("INC", Mem(_runtimeNmiCounterAddress));
                foreach (int address in queueScratch.Reverse()) { EmitAsm("PLA"); EmitAsm("STA", Mem(address)); }
                EmitAsm("PLA"); EmitAsm("TAY"); EmitAsm("PLA"); EmitAsm("TAX"); EmitAsm("PLA");
                EmitAsm("RTI");
            }

Masque les 64 sprites du tampon miroir de la page 02 en réglant chaque octet Y sur 0xF0. Les numéros de tuiles, les attributs et les coordonnées X sont conservés.

Syntaxe

void __oam_clear(void);

Valeur renvoyée

Aucune (void).

Conditions et limites

Ces opérations modifient la RAM CPU 0x0200–0x02FF, sans mettre immédiatement à jour l’OAM matérielle. Transférez la page complète avec __oam_dma. Elles ne tiennent à jour ni les indicateurs d’allocation, ni les tableaux de coordonnées, ni le compteur de la bibliothèque de sprites. Évitez qu’une interruption modifie ou transfère une page encore en préparation.

Exemple d’utilisation

__sprite_set(63,144,111,128,0); // Seed the CLEAR row with a visible entry.
__oam_clear(); // Set every Y byte to 240; tile, attributes and X are retained.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple réserve une ligne légendée à chaque opération. SET et MOVE montrent des flèches de 8×8 vers la droite en (144,16) et (144,32) ; TILE, un carré vert en (144,48) ; ATTR, la flèche retournée selon les deux axes en (144,64). HIDE en (144,80) et CLEAR en (144,112) doivent rester vides. META montre une paire en (136,96) et (144,96), la seconde flèche étant retournée horizontalement. NEXT 07 indique l’indice suivant après les entrées 5 et 6. Les bords sont rouges, la tige verte et les détails de la pointe bleus. La vérification compare 8 704 pixels par image et les octets OAM transférés ; le matériel physique n’a pas été testé.

TRANSFER montre une flèche en (144,128). Ce programme envoie directement la page 02 avec __oam_dma, y compris tous les champs préparés par les opérations individuelles sur les sprites.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\oam_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\sprite_example.chr -o .\out\oam_intrinsics.nes --no-cache --no-disasm

Hide all 64 page-02 shadow sprites by writing Y=F0; hardware OAM changes only after DMA.

EmitHelperStart("__oam_clear");
            EmitAsm("LDX", Imm(0));
            EmitAsm("LDA", Imm(0xF0));
            string loop = NewGeneratedLabel("oam_clear_loop");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("STA", new AsmOperand(0x0200, AddressMode.AbsoluteX));
            EmitAsm("INX"); EmitAsm("INX"); EmitAsm("INX"); EmitAsm("INX");
            EmitAsm("BNE", Rel(loop));
            EmitAsm("RTS");

Transfère les 256 octets de la page miroir 0x0200–0x02FF vers l’OAM matérielle, à partir de l’entrée 0. Le CPU est suspendu pendant le transfert et reprend son exécution à la fin.

Syntaxe

void __oam_dma(void);

Valeur renvoyée

Aucune (void).

Conditions et limites

Appelez pendant le VBlank ou avec le rendu désactivé ; aucune des deux fonctions DMA n’attend le VBlank. Elles remettent OAMADDR à zéro avant le transfert. Le matériel suspend normalement le CPU pendant 513 ou 514 cycles ; l’activité DMC peut prolonger cette durée. KUROSAKI l’approxime à 513 cycles : la vérification des images ne confirme donc pas la temporisation matérielle exacte. KQ2421 peut apparaître même après une attente explicite du VBlank, car le compilateur classe les appels selon le nom de l’appelant.

Exemple d’utilisation

m_wait();__oam_dma(); // Transfer all 256 bytes from page 02 at VBlank.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple réserve une ligne légendée à chaque opération. SET et MOVE montrent des flèches de 8×8 vers la droite en (144,16) et (144,32) ; TILE, un carré vert en (144,48) ; ATTR, la flèche retournée selon les deux axes en (144,64). HIDE en (144,80) et CLEAR en (144,112) doivent rester vides. META montre une paire en (136,96) et (144,96), la seconde flèche étant retournée horizontalement. NEXT 07 indique l’indice suivant après les entrées 5 et 6. Les bords sont rouges, la tige verte et les détails de la pointe bleus. La vérification compare 8 704 pixels par image et les octets OAM transférés ; le matériel physique n’a pas été testé.

TRANSFER montre une flèche en (144,128). Ce programme envoie directement la page 02 avec __oam_dma, y compris tous les champs préparés par les opérations individuelles sur les sprites.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\oam_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\sprite_example.chr -o .\out\oam_intrinsics.nes --no-cache --no-disasm

OAM / input
Set OAMADDR to zero and start DMA from CPU page 02; arrange safe PPU timing in the caller.

case "__oam_dma": if (!Need(0)) return true; EmitAsm("LDA", Imm(0)); EmitAsm("STA", Mem(0x2003)); EmitAsm("LDA", Imm(0x02)); EmitAsm("STA", Mem(0x4014)); return true;

Transfère 256 octets de la page mémoire CPU sélectionnée vers l’OAM matérielle, à partir de l’entrée 0. Une page OAM préparée séparément peut ainsi être utilisée sans copie préalable vers la page 02. La source n’est pas modifiée.

Syntaxe

void __oam_dma_page(u8 page);

Paramètres

page

Octet de poids fort de l’adresse CPU source : passez 4 pour 0x0400–0x04FF, et non 0x0400. Fournissez une page complète de 256 octets lisibles et gardez le banc requis accessible. Évitez les pages contenant des registres d’E/S, dont la lecture peut avoir des effets de bord. La source n’est pas validée.

Valeur renvoyée

Aucune (void).

Conditions et limites

Appelez pendant le VBlank ou avec le rendu désactivé ; aucune des deux fonctions DMA n’attend le VBlank. Elles remettent OAMADDR à zéro avant le transfert. Le matériel suspend normalement le CPU pendant 513 ou 514 cycles ; l’activité DMC peut prolonger cette durée. KUROSAKI l’approxime à 513 cycles : la vérification des images ne confirme donc pas la temporisation matérielle exacte. KQ2421 peut apparaître même après une attente explicite du VBlank, car le compilateur classe les appels selon le nom de l’appelant.

Exemple d’utilisation

m_wait();__oam_dma_page(4); // The argument is a page number, not 0x0400.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple réserve une ligne légendée à chaque opération. SET et MOVE montrent des flèches de 8×8 vers la droite en (144,16) et (144,32) ; TILE, un carré vert en (144,48) ; ATTR, la flèche retournée selon les deux axes en (144,64). HIDE en (144,80) et CLEAR en (144,112) doivent rester vides. META montre une paire en (136,96) et (144,96), la seconde flèche étant retournée horizontalement. NEXT 07 indique l’indice suivant après les entrées 5 et 6. Les bords sont rouges, la tige verte et les détails de la pointe bleus. La vérification compare 8 704 pixels par image et les octets OAM transférés ; le matériel physique n’a pas été testé.

Cette variante copie la page 02 préparée dans un tableau séparé à 0x0400, puis ne change que la tuile de l’entrée 7, qui devient 129. __oam_dma_page(4) doit afficher un carré vert en (144,128), face à TRANSFER, tandis que la page 02 conserve la tuile 128 de la flèche. Les autres lignes correspondent à l’exemple par défaut. Les 256 octets OAM sont comparés à la page 04 et l’intégrité de la page 02 est vérifiée.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\oam_page.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\sprite_example.chr -o .\out\oam_page.nes --no-cache --no-disasm

Set OAMADDR to zero and DMA 256 bytes from page<<8. The source page must remain readable.

case "__oam_dma_page": if (!Need(1)) return true; EmitAsm("LDA", Imm(0)); EmitAsm("STA", Mem(0x2003)); Load1(args[0]); EmitAsm("STA", Mem(0x4014)); return true;

Conserve les bits 0–3 de l’état NES fourni (pad & 0x0F) : A, B, Select et Start. Filtre uniquement une valeur déjà lue, sans accéder au matériel du contrôleur.

Syntaxe

u8 __pad_buttons(u8 pad);

Paramètres

pad

Un état NES de 8 bits déjà lu, par exemple le résultat de __pad_read1_safe(). Passez la valeur elle-même, pas un pointeur, un numéro de port ou un masque logique input_*.

Valeur renvoyée

Masque de 0 à 15 dans l’ordre indiqué. Plusieurs bits peuvent être actifs ; testez un bouton avec result & bit plutôt qu’en comparant tout le résultat à 1.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Exemple d’utilisation

buttons=__pad_buttons(raw1); // Low nibble of 129: 1, the A button.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare les deux ports, les lectures simples et avec vérification de concordance, les filtres et les macros abrégées. Maintenez A + droite sur la manette 1 et B + gauche sur la manette 2. RAW P1, SAFE P1 et ALIAS P1 valent 129 ; les trois valeurs P2 sont 66. BUTTONS P1 vaut 1 et DIRS P1 vaut 128 : le filtre des directions conserve la position des bits de poids fort. FAILED CHECKS doit valoir 0. Les valeurs restent affichées.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\input_raw.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\input_raw.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm --no-cache

Return pad & 0F for A/B/Select/Start; this masks a supplied snapshot and performs no polling.

Conserve les bits 4–7 de l’état NES (pad & 0xF0) : haut, bas, gauche et droite. Les positions sont conservées ; droite seule renvoie 128, pas 8. Aucune lecture du contrôleur n’est effectuée.

Syntaxe

u8 __pad_dirs(u8 pad);

Paramètres

pad

Un état NES de 8 bits déjà lu, par exemple le résultat de __pad_read1_safe(). Passez la valeur elle-même, pas un pointeur, un numéro de port ou un masque logique input_*.

Valeur renvoyée

La valeur fournie ET 0xF0 : 0, 16, 32, …, 240. Les directions restent dans les bits 4–7.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Exemple d’utilisation

directions=__pad_dirs(raw1); // High nibble retained in place: 128, not 8.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare les deux ports, les lectures simples et avec vérification de concordance, les filtres et les macros abrégées. Maintenez A + droite sur la manette 1 et B + gauche sur la manette 2. RAW P1, SAFE P1 et ALIAS P1 valent 129 ; les trois valeurs P2 sont 66. BUTTONS P1 vaut 1 et DIRS P1 vaut 128 : le filtre des directions conserve la position des bits de poids fort. FAILED CHECKS doit valoir 0. Les valeurs restent affichées.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\input_raw.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\input_raw.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm --no-cache

Return pad & F0 in the original bit positions; this does not normalize directions to bits 0..3.

Verrouille l’état des deux contrôleurs en écrivant 1 puis 0 dans $4016, puis lit les huit bits série D0 du contrôleur 1 à $4016. Renvoie un état de maintien au format NES, sans nouvel essai ni calcul de transition.

Syntaxe

u8 __pad_read1(void);

Valeur renvoyée

Masque de maintien de 8 bits dans l’ordre NES. Chaque bit à 1 identifie un bouton appuyé ; 0 signifie aucun. Ce n’est pas un booléen normalisé.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Cet appel lit un nouvel état matériel. Il ne met pas à jour les états mémorisés input_* ou nes_pad1_* et ne produit ni événements d’appui ou de relâchement, ni répétitions. Mémorisez le résultat et comparez-le à votre masque précédent pour détecter les transitions.

Exemple d’utilisation

raw1=__pad_read1(); // Controller 1: A (1) | Right (128) = 129.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare les deux ports, les lectures simples et avec vérification de concordance, les filtres et les macros abrégées. Maintenez A + droite sur la manette 1 et B + gauche sur la manette 2. RAW P1, SAFE P1 et ALIAS P1 valent 129 ; les trois valeurs P2 sont 66. BUTTONS P1 vaut 1 et DIRS P1 vaut 128 : le filtre des directions conserve la position des bits de poids fort. FAILED CHECKS doit valoir 0. Les valeurs restent affichées.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\input_raw.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\input_raw.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm --no-cache

Latch and sample eight D0 bits from port 1; bit order is A,B,Select,Start,Up,Down,Left,Right.

Lit huit bits série sur l’entrée d’extension D1 à $4016. Écrit 1 puis 0 dans $4016 pour verrouiller les états, lit huit fois le bit 1 et place les échantillons successifs dans les bits 0–7 du résultat. Il s’agit d’une lecture du canal D1 du port 1 ; le canal D0 de la manette ordinaire n’est pas lu et aucun nouvel essai ne recherche des valeurs concordantes.

Syntaxe

u8 __pad_read1_d1(void);

Valeur renvoyée

Masque de maintien de 8 bits dans l’ordre NES. Chaque bit à 1 identifie un bouton appuyé ; 0 signifie aucun. Ce n’est pas un booléen normalisé.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Utilisez un périphérique fournissant un flux série de manette compatible sur huit bits par la ligne D1 choisie. La fonction n’identifie pas le périphérique et ne prend pas en charge tous les protocoles d’extension. Chaque appel verrouille à nouveau les deux flux de contrôleurs ; terminez une lecture complète avant d’en commencer une autre. Les résultats sont de nouvelles lectures qui ne mettent pas à jour les états input_* ou nes_pad1_*.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Exemple d’utilisation

d1_first=__pad_read1_d1();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare l’entrée ordinaire D0, l’extension D1 et le niveau numérique du microphone. Maintenez A sur la manette 1 et B sur la manette 2 jusqu’à la capture. NORMAL P1 et NORMAL P2 affichent 001 et 002. Dans l’exécution KUROSAKI fournie, D1 PORT 1, D1 PORT 2, EXP ALIAS 1, EXP ALIAS 2, MIC LEVEL et MIC DIRECT affichent 000, car ces lignes ne sont pas émulées. Les valeurs restent ensuite fixes. Avec des périphériques adaptés et leurs lignes implémentées, les valeurs dépendent des entrées réelles ; interprétez-les selon les bits décrits ci-dessus au lieu d’attendre ces zéros.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\expansion_input.c -I .\kitaq-docs\samples -I .\kitaqfc\lib -o .\out\expansion_input.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Famicom/NES expansion input devices.
D1 readers are for expansion-port controllers/joysticks that expose a
standard 8-bit joypad stream on data line D1 instead of D0.
__joypad2p_voice() / __mic_read2p() return the Famicom 2P microphone bit.

Latch and read an eight-button stream from port-1 data line D1 rather than D0.

Lit le contrôleur 1 par paires d’appels complets à __pad_read1(). Renvoie le masque NES lorsque les deux lectures concordent. Le résultat décrit le maintien, pas les nouveaux appuis.

Syntaxe

u8 __pad_read1_safe(void);

Valeur renvoyée

Masque de maintien de 8 bits dans l’ordre NES. Chaque bit à 1 identifie un bouton appuyé ; 0 signifie aucun. Ce n’est pas un booléen normalisé.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Cet appel lit un nouvel état matériel. Il ne met pas à jour les états mémorisés input_* ou nes_pad1_* et ne produit ni événements d’appui ou de relâchement, ni répétitions. Mémorisez le résultat et comparez-le à votre masque précédent pour détecter les transitions.

La lecture sûre répète des paires de lectures complètes jusqu’à obtenir deux masques identiques. Chaque lecture active le strobe de $4016 et redémarre la lecture série des deux contrôleurs. Le nombre d’essais n’est pas limité. Ce contrôle ne prouve pas la compatibilité avec toutes les combinaisons DMC/périphériques.

Exemple d’utilisation

safe1=__pad_read1_safe(); // Repeat paired controller-1 reads until they agree.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare les deux ports, les lectures simples et avec vérification de concordance, les filtres et les macros abrégées. Maintenez A + droite sur la manette 1 et B + gauche sur la manette 2. RAW P1, SAFE P1 et ALIAS P1 valent 129 ; les trois valeurs P2 sont 66. BUTTONS P1 vaut 1 et DIRS P1 vaut 128 : le filtre des directions conserve la position des bits de poids fort. FAILED CHECKS doit valoir 0. Les valeurs restent affichées.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\input_raw.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\input_raw.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm --no-cache

Repeat pairs of port-1 polls until both bytes match; the retry loop has no fixed limit.

Verrouille l’état des deux contrôleurs en écrivant 1 puis 0 dans $4016, puis lit les huit bits série D0 du contrôleur 2 à $4017. Renvoie un état de maintien au format NES, sans nouvel essai ni calcul de transition.

Syntaxe

u8 __pad_read2(void);

Valeur renvoyée

Masque de maintien de 8 bits dans l’ordre NES. Chaque bit à 1 identifie un bouton appuyé ; 0 signifie aucun. Ce n’est pas un booléen normalisé.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Cet appel lit un nouvel état matériel. Il ne met pas à jour les états mémorisés input_* ou nes_pad1_* et ne produit ni événements d’appui ou de relâchement, ni répétitions. Mémorisez le résultat et comparez-le à votre masque précédent pour détecter les transitions.

Exemple d’utilisation

raw2=__pad_read2(); // Controller 2: B (2) | Left (64) = 66.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare les deux ports, les lectures simples et avec vérification de concordance, les filtres et les macros abrégées. Maintenez A + droite sur la manette 1 et B + gauche sur la manette 2. RAW P1, SAFE P1 et ALIAS P1 valent 129 ; les trois valeurs P2 sont 66. BUTTONS P1 vaut 1 et DIRS P1 vaut 128 : le filtre des directions conserve la position des bits de poids fort. FAILED CHECKS doit valoir 0. Les valeurs restent affichées.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\input_raw.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\input_raw.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm --no-cache

Latch and sample eight D0 bits from port 2 in the same NES button order.

Lit huit bits série sur l’entrée d’extension D1 à $4017. Écrit 1 puis 0 dans $4016 pour verrouiller les états, lit huit fois le bit 1 et place les échantillons successifs dans les bits 0–7 du résultat. Il s’agit d’une lecture du canal D1 du port 2 ; le canal D0 de la manette ordinaire n’est pas lu et aucun nouvel essai ne recherche des valeurs concordantes.

Syntaxe

u8 __pad_read2_d1(void);

Valeur renvoyée

Masque de maintien de 8 bits dans l’ordre NES. Chaque bit à 1 identifie un bouton appuyé ; 0 signifie aucun. Ce n’est pas un booléen normalisé.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Utilisez un périphérique fournissant un flux série de manette compatible sur huit bits par la ligne D1 choisie. La fonction n’identifie pas le périphérique et ne prend pas en charge tous les protocoles d’extension. Chaque appel verrouille à nouveau les deux flux de contrôleurs ; terminez une lecture complète avant d’en commencer une autre. Les résultats sont de nouvelles lectures qui ne mettent pas à jour les états input_* ou nes_pad1_*.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Exemple d’utilisation

d1_second=__pad_read2_d1();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare l’entrée ordinaire D0, l’extension D1 et le niveau numérique du microphone. Maintenez A sur la manette 1 et B sur la manette 2 jusqu’à la capture. NORMAL P1 et NORMAL P2 affichent 001 et 002. Dans l’exécution KUROSAKI fournie, D1 PORT 1, D1 PORT 2, EXP ALIAS 1, EXP ALIAS 2, MIC LEVEL et MIC DIRECT affichent 000, car ces lignes ne sont pas émulées. Les valeurs restent ensuite fixes. Avec des périphériques adaptés et leurs lignes implémentées, les valeurs dépendent des entrées réelles ; interprétez-les selon les bits décrits ci-dessus au lieu d’attendre ces zéros.

Le modèle de contrôleurs du KUROSAKI publié ne renvoie que D0 et le bit 6 fixe. D1 et le bit du microphone valent donc toujours 0 dans cet émulateur, même lorsqu’un bouton ordinaire est maintenu. L’exécution fournie vérifie la compilation, l’entrée normale et cette observation de signal nul. Les signaux périphériques non nuls, les délais électriques et la compatibilité matérielle restent non vérifiés ; un zéro ici ne prouve ni le bon fonctionnement du périphérique ni l’impossibilité de le lire sur une machine réelle.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\expansion_input.c -I .\kitaq-docs\samples -I .\kitaqfc\lib -o .\out\expansion_input.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Latch and read an eight-button stream from port-2 data line D1 rather than D0.

Lit le contrôleur 2 par paires d’appels complets à __pad_read2(). Renvoie le masque NES lorsque les deux lectures concordent. Le résultat décrit le maintien, pas les nouveaux appuis.

Syntaxe

u8 __pad_read2_safe(void);

Valeur renvoyée

Masque de maintien de 8 bits dans l’ordre NES. Chaque bit à 1 identifie un bouton appuyé ; 0 signifie aucun. Ce n’est pas un booléen normalisé.

Conditions et limites

Format NES brut : A=0x01, B=0x02, SELECT=0x04, START=0x08, UP=0x10, DOWN=0x20, LEFT=0x40, RIGHT=0x80. Un bit à 1 indique un appui. Utilisez ces valeurs avec nes_pad_* et les résultats bruts de __pad_*, et non les masques communs BTN_* de input.h.

Cet appel lit un nouvel état matériel. Il ne met pas à jour les états mémorisés input_* ou nes_pad1_* et ne produit ni événements d’appui ou de relâchement, ni répétitions. Mémorisez le résultat et comparez-le à votre masque précédent pour détecter les transitions.

La lecture sûre répète des paires de lectures complètes jusqu’à obtenir deux masques identiques. Chaque lecture active le strobe de $4016 et redémarre la lecture série des deux contrôleurs. Le nombre d’essais n’est pas limité. Ce contrôle ne prouve pas la compatibilité avec toutes les combinaisons DMC/périphériques.

Exemple d’utilisation

safe2=__pad_read2_safe(); // The same consistency check on controller 2.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme compare les deux ports, les lectures simples et avec vérification de concordance, les filtres et les macros abrégées. Maintenez A + droite sur la manette 1 et B + gauche sur la manette 2. RAW P1, SAFE P1 et ALIAS P1 valent 129 ; les trois valeurs P2 sont 66. BUTTONS P1 vaut 1 et DIRS P1 vaut 128 : le filtre des directions conserve la position des bits de poids fort. FAILED CHECKS doit valoir 0. Les valeurs restent affichées.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\input_raw.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\input_raw.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm --no-cache

Repeat pairs of port-2 polls until both bytes match; this does not populate pad.c globals.

Réinitialise le verrou PPU, définit 0x3F00 et écrit exactement 16 octets de la source via PPUDATA pour les quatre palettes de fond. Le transfert est immédiat ; il ne change pas les sélections de palette des attributs et ne charge pas de graphismes de tuiles.

Syntaxe

void __palette_bg_load(const u8* pal16);

Paramètres

pal16

Pointeur CPU vers 16 octets lisibles de codes de palette NES, pas de triplets RGB. Maintenez la banque source accessible jusqu’au retour synchrone ; aucun changement de banque ni contrôle de longueur n’est effectué. Utilisez l’incrément PPU 1 pour atteindre les 16 adresses prévues.

Valeur renvoyée

Aucune (void).

Conditions et limites

Les adresses PPU 0x3F10/14/18/1C sont des alias de 0x3F00/04/08/0C. Charger la palette de sprites écrit donc aussi ces entrées du fond. Le compilateur transmet les octets tels quels, sans valider les couleurs, fusionner les palettes ni préserver les entrées partagées.

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__palette_bg_load(scene_palette); // Four background palettes, 16 bytes total.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Stream exactly 16 source bytes to 3F00. Arrange PPU access timing and increment one.

case "__palette_bg_load": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2}, funcName);

void EmitHelperPalette(string name, int ppuAddress)
        {
            EmitHelperStart(name);
            EmitAsm("LDA", Mem(0x2002));
            EmitAsm("LDA", Imm((ppuAddress >> 8) & 0xFF));
            EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Imm(ppuAddress & 0xFF));
            EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDY", Imm(0));
            string loop = NewGeneratedLabel("pal_loop");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LDA", IndY(CallArgBase));
            EmitAsm("STA", Mem(0x2007));
            EmitAsm("INY");
            EmitAsm("CPY", Imm(16));
            EmitAsm("BNE", Rel(loop));
            EmitAsm("RTS");
        }

EmitHelperPalette("__palette_bg_load", 0x3F00);

Réinitialise le verrou PPU, définit 0x3F10 et écrit exactement 16 octets de la source via PPUDATA pour les quatre palettes de sprites. Les bits d’attribut du sprite choisissent la palette affichée. Ne modifie pas OAM et ne transfère pas les graphismes de sprites.

Syntaxe

void __palette_sp_load(const u8* pal16);

Paramètres

pal16

Pointeur CPU vers 16 octets lisibles de codes de palette NES, pas de triplets RGB. Maintenez la banque source accessible jusqu’au retour synchrone ; aucun changement de banque ni contrôle de longueur n’est effectué. Utilisez l’incrément PPU 1 pour atteindre les 16 adresses prévues.

Valeur renvoyée

Aucune (void).

Conditions et limites

Les adresses PPU 0x3F10/14/18/1C sont des alias de 0x3F00/04/08/0C. Charger la palette de sprites écrit donc aussi ces entrées du fond. Le compilateur transmet les octets tels quels, sans valider les couleurs, fusionner les palettes ni préserver les entrées partagées.

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__palette_sp_load(scene_palette); // Four sprite palettes, 16 bytes total.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Stream exactly 16 source bytes to 3F10; hardware palette aliases also affect background entries.

case "__palette_sp_load": return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2}, funcName);
                // Clear queued length and readiness; the overflow indicator has a separate reset intrinsic.

void EmitHelperPalette(string name, int ppuAddress)
        {
            EmitHelperStart(name);
            EmitAsm("LDA", Mem(0x2002));
            EmitAsm("LDA", Imm((ppuAddress >> 8) & 0xFF));
            EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDA", Imm(ppuAddress & 0xFF));
            EmitAsm("STA", Mem(0x2006));
            EmitAsm("LDY", Imm(0));
            string loop = NewGeneratedLabel("pal_loop");
            _assembly.Add(Expr.Make(Tag.Label, loop));
            EmitAsm("LDA", IndY(CallArgBase));
            EmitAsm("STA", Mem(0x2007));
            EmitAsm("INY");
            EmitAsm("CPY", Imm(16));
            EmitAsm("BNE", Rel(loop));
            EmitAsm("RTS");
        }

EmitHelperPalette("__palette_sp_load", 0x3F10);

Évalue ppu_addr une fois, lit PPUSTATUS pour réinitialiser le verrou partagé, puis écrit les octets de poids fort et faible dans PPUADDR. Définit la destination des prochains accès à PPUDATA sans écrire de données. La PPU applique ses masques et miroirs d’adresse.

Syntaxe

void __ppu_addr(u16 ppu_addr);

Paramètres

ppu_addr

Adresse PPU en octets (0x0000–0x3FFF), et non pointeur CPU. La destination doit être inscriptible : modifier les motifs exige de la CHR RAM, pas de la CHR ROM. Le mappage et le mirroring PPU s’appliquent. Pour les copies et remplissages contigus, choisissez l’incrément 1 dans PPUCTRL. Exécutez à un instant sûr, puis rétablissez le défilement voulu ; l’exécuteur écrit PPUADDR et PPUDATA sans restaurer le défilement.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

address_port=0x21;
__ppu_addr(0x2192); // Reset latch and set the cell at tile (18,12).

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Set the PPU address through the compiler helper; address writes affect the shared scroll/address latch.

case "__ppu_addr":
                    if (!Need(1)) return true;
                    PpuAddr(args[0]); return true;

void PpuAddr(Expr e)
            {
                int[] t = AcquireTemps(2);
                try
                {
                    EmitLoadValue(e, ctx, 2);
                    EmitAsm("STA", Mem(t[0]));
                    EmitAsm("STX", Mem(t[1]));
                    EmitAsm("LDA", Mem(0x2002));
                    EmitAsm("LDA", Mem(t[1]));
                    EmitAsm("STA", Mem(0x2006));
                    EmitAsm("LDA", Mem(t[0]));
                    EmitAsm("STA", Mem(0x2006));
                }
                finally { ReleaseTemps(t); }
            }

Renvoie la copie logicielle de PPUCTRL. Utilisez-la pour sauvegarder l’activation NMI, le choix de la table de motifs et l’incrément d’adresse avant une modification temporaire.

Syntaxe

u8 __ppu_ctrl_get(void);

Valeur renvoyée

Renvoie en u8 la dernière valeur de contrôle conservée par la bibliothèque ou les fonctions intrinsèques de réglage. Ne lit pas PPUSTATUS.

Conditions et limites

PPUCTRL et PPUMASK sont accessibles en écriture seule. Cette fonction ne lit pas le matériel. Les écritures directes dans $2000/$2001 ou le code assembleur personnalisé contournent les copies logicielles. Utilisez systématiquement les opérations __ppu_*_set correspondantes. Lire la copie ne change ni le verrou ni l’état des interruptions.

Exemple d’utilisation

__ppu_ctrl_set(4);
    if(__ppu_ctrl_get()!=4)failures=1; // Inspect the software shadow, not PPUSTATUS.
    __ppu_ctrl_set(0);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

La solution prépare l’écran sans rendu, installe les palettes, efface tuiles et attributs, puis dessine ce test. Un motif bleu de tuiles pleines, demi-barres gauches et triangles commence en (0,16) ; un bloc vert plein commence en (0,96). Chaque région mesure 256×64 pixels, sauf sa dernière case de 8×8 en (248,72) ou (248,152), qui reste noire car le transfert contient 255 octets de tuiles. À y=208, les formes rouges sont un carré de 8×8 en x=16, une barre gauche de 4×8 en x=224 et un triangle de huit lignes en x=240. FAILED CHECKS indique 0. Des tests d’état distincts confirment les deux registres de contrôle, le transfert des 32 octets de palette et l’effacement des 1 024 octets de la table de noms. Les quatre appels déclarés doivent échouer à l’édition de liens.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_implemented.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\ppu_implemented.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr --no-cache --no-disasm

Read the software PPUCTRL/PPUMASK shadows; use the setters for coherent state.
Raw writes to $2000/$2001 bypass these shadows. No PPU hardware read occurs.

case "__ppu_ctrl_get":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Mem(_runtimePpuCtrlShadowAddress)); return true;

Remplace PPUCTRL et sa copie logicielle par l’octet fourni. Contrôle NMI, l’incrément d’adresse PPU, les tables de motifs, la taille des sprites et la table de noms de base. Ne modifie pas PPUMASK et ne conserve pas les bits non spécifiés.

Syntaxe

void __ppu_ctrl_set(u8 value);

Paramètres

value

Octet non signé de 0..255, écrit tel quel. C’est un octet complet de registre ou de données, pas un booléen ni un numéro de bit.

Valeur renvoyée

Aucune (void).

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__ppu_ctrl_set(0x80); // NMI enabled, increment 1, nametable/pattern tables 0.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Replace PPUCTRL, including NMI enable, pattern-table choices and address increment mode.

case "__ppu_ctrl_set":
                    if (!Need(1)) return true;
                    Store1(args[0], _runtimePpuCtrlShadowAddress); EmitAsm("STA", Mem(0x2000)); return true;
                // Read software state: the corresponding hardware registers are write-only.

Écrit value une fois dans PPUDATA à l’adresse PPU courante. Celle-ci avance ensuite de 1 ou 32 selon PPUCTRL. Cet appel ne définit pas l’adresse, ne réinitialise pas le verrou et ne met pas le transfert en file.

Syntaxe

void __ppu_data(u8 value);

Paramètres

value

Octet non signé de 0..255, écrit tel quel. C’est un octet complet de registre ou de données, pas un booléen ni un numéro de bit.

Valeur renvoyée

Aucune (void).

Conditions et limites

L’accès direct à la PPU exige de désactiver le rendu ou de terminer toute l’opération dans un intervalle VBlank sûr. Ces fonctions n’attendent pas, ne mettent rien en file, ne bloquent pas NMI et ne rétablissent pas le défilement. Empêchez une interruption de modifier le verrou ou l’adresse partagés pendant l’appel. Le bit 2 de PPUCTRL choisit un pas de destination de 1 ou 32 par octet. La PPU gère les miroirs et le bouclage des adresses ; la CHR-ROM n’est pas inscriptible. Rétablissez le défilement voulu avant le rendu.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__ppu_data(3); // Green triangle at (144,96); destination advances by one.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Write one PPUDATA byte using the current PPU address and increment mode.

case "__ppu_data":
                    if (!Need(1)) return true;
                    Load1(args[0]); EmitAsm("STA", Mem(0x2007)); return true;
                // Reading PPUSTATUS also has hardware side effects; this is not a side-effect-free status cache.

Renvoie la copie logicielle de PPUMASK. Utilisez-la pour conserver les réglages de rendu, de visibilité du bord gauche, de niveaux de gris et d’accentuation des couleurs.

Syntaxe

u8 __ppu_mask_get(void);

Valeur renvoyée

Renvoie en u8 la dernière valeur de contrôle conservée par la bibliothèque ou les fonctions intrinsèques de réglage. Ne lit pas PPUSTATUS.

Conditions et limites

PPUCTRL et PPUMASK sont accessibles en écriture seule. Cette fonction ne lit pas le matériel. Les écritures directes dans $2000/$2001 ou le code assembleur personnalisé contournent les copies logicielles. Utilisez systématiquement les opérations __ppu_*_set correspondantes. Lire la copie ne change ni le verrou ni l’état des interruptions.

Exemple d’utilisation

__ppu_mask_set(0xE7);
    if(__ppu_mask_get()!=0xE7)failures=1;
    __ppu_mask_set(0);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

La solution prépare l’écran sans rendu, installe les palettes, efface tuiles et attributs, puis dessine ce test. Un motif bleu de tuiles pleines, demi-barres gauches et triangles commence en (0,16) ; un bloc vert plein commence en (0,96). Chaque région mesure 256×64 pixels, sauf sa dernière case de 8×8 en (248,72) ou (248,152), qui reste noire car le transfert contient 255 octets de tuiles. À y=208, les formes rouges sont un carré de 8×8 en x=16, une barre gauche de 4×8 en x=224 et un triangle de huit lignes en x=240. FAILED CHECKS indique 0. Des tests d’état distincts confirment les deux registres de contrôle, le transfert des 32 octets de palette et l’effacement des 1 024 octets de la table de noms. Les quatre appels déclarés doivent échouer à l’édition de liens.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_implemented.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\ppu_implemented.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr --no-cache --no-disasm

case "__ppu_mask_get":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Mem(_runtimePpuMaskShadowAddress)); return true;
                // Direct PPU address/data access does not wait for a safe rendering interval here.

Remplace tout l’octet PPUMASK et sa copie logicielle par value. Choisissez explicitement rendu, bord gauche, niveaux de gris et accentuation. Ne fusionne pas les bits avec le masque précédent et ne modifie pas PPUCTRL.

Syntaxe

void __ppu_mask_set(u8 value);

Paramètres

value

Octet non signé de 0..255, écrit tel quel. C’est un octet complet de registre ou de données, pas un booléen ni un numéro de bit.

Valeur renvoyée

Aucune (void).

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__ppu_mask_set(0x0A); // Background enabled, including its leftmost eight pixels.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Replace PPUMASK with the supplied byte; the caller chooses rendering, clipping and emphasis bits.

case "__ppu_mask_set":
                    if (!Need(1)) return true;
                    Store1(args[0], _runtimePpuMaskShadowAddress); EmitAsm("STA", Mem(0x2001)); return true;
                // Update the PPUCTRL shadow before writing the hardware register.

Écrit zéro dans PPUMASK et sa copie logicielle, désactivant le fond et les sprites. Efface tous les bits, y compris les niveaux de gris et l’accentuation. PPUCTRL et l’activation de NMI restent inchangés ; contrôlez NMI séparément pour préparer des transferts partagés.

Syntaxe

void __ppu_off(void);

Valeur renvoyée

Aucune (void).

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__ppu_off(); // PPUMASK and its software shadow become zero; NMI is unchanged.
__ppu_ctrl_set(0); // Disable NMI separately while preparing the whole scene.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Invoke the compiler rendering-disable helper before bulk direct PPU updates.

case "__ppu_off":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Imm(0)); EmitAsm("STA", Mem(_runtimePpuMaskShadowAddress)); EmitAsm("STA", Mem(0x2001)); return true;
                // Keep the supplied mask available for later runtime code that restores PPU state.

Remplace PPUMASK et sa copie logicielle par 0x1E, activant le fond et les sprites, y compris les huit pixels du bord gauche. Écrase les choix de niveaux de gris et d’accentuation des couleurs ; ne modifie pas PPUCTRL et n’active pas NMI.

Syntaxe

void __ppu_on(void);

Valeur renvoyée

Aucune (void).

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

__ppu_on(); // Replace mask with 0x1E: enable sprites and background at both edges.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

PRG bank
Resolve a symbol or function placement to its byte bank number at compilation time.
u8 __bankof(u16 symbol_or_function);
Select the mapper-specific PRG bank; the common bank and legal bank range depend on the target board.
void __bankswitch(u8 bank);
Use the same mapper PRG-switch helper as __bankswitch; retain executable code in a valid mapping.
void __prg_bank_set(u8 bank);
Call a declared zero-argument function; placement selects its bank and its declared type determines the result.
u8 __farcall(u8 bank, u16 func);
Switch to the source bank, copy len bytes forward and restore the previous bank.
Keep destination RAM and helper code accessible throughout; overlapping copies are not memmove.
void __far_memcpy(u8* dst, u8 bank, u16 src, u16 len);
Temporarily select bank, read one byte at addr and restore the prior bank mapping.
u8 __farpeek8(u8 bank, u16 addr);
Temporarily select bank and read a little-endian word, then restore the previous mapping.
u16 __farpeek16(u8 bank, u16 addr);

 PPU / VRAM
Invoke the compiler rendering-enable helper; this header contains declarations, not C fallback implementations.

case "__ppu_on":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Imm(0x1E)); EmitAsm("STA", Mem(_runtimePpuMaskShadowAddress)); EmitAsm("STA", Mem(0x2001)); return true;

Lit PPUSTATUS une fois et renvoie l’octet observé avant que la lecture efface le drapeau VBlank. Réinitialise aussi le verrou partagé de défilement et d’adresse. Il s’agit d’une lecture matérielle avec effets de bord, pas d’un compteur de trames mémorisé ni d’un test de fin de NMI.

Syntaxe

u8 __ppu_read_status(void);

Valeur renvoyée

Octet d’état brut. Le bit 7 indique VBlank, le 6 la rencontre avec le sprite zéro et le 5 le débordement de sprites. Testez le drapeau voulu avec un masque ; ne traitez pas l’octet entier comme un booléen ou un numéro de trame. Les bits faibles ne constituent pas un état applicatif portable.

Conditions et limites

Une lecture de PPUSTATUS peut affecter NMI et les prochaines écritures dans PPUSCROLL et PPUADDR. Ne l’insérez pas entre les deux octets d’une autre routine. Ces appels n’attendent pas VBlank et ne terminent pas les files de transfert en attente.

NESdev : registres du PPU

NESdev : défilement du PPU

Exemple d’utilisation

address_port=0x21;
status_snapshot=__ppu_read_status(); // Also resets the shared write latch.
address_port=0x21;address_port=0x84;data_port=3; // Blue triangle at (32,96).

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme présente les registres, les écritures directes de tuiles et d’attributs, le défilement et le chargement séparé des palettes de fond et de sprites. La bande bleue en (0,16) mesure 256×16 pixels : la première ligne répète une tuile pleine de 8×8, une barre gauche de 4×8 et un triangle de huit lignes ; la seconde contient uniquement des barres. Un rectangle vert plein de 64×32 commence en (16,48). La région rouge de 64×32 en (144,48) contient une grille de 8 par 4 tuiles triangulaires.

À y=96, les repères bleus en x=16, 24 et 32 sont un carré, une barre gauche et un triangle ; une barre gauche rouge est en x=80 et un triangle vert en x=144. Ce sont des tuiles de fond. À y=144, les sprites avec leur propre palette sont un carré rouge de 8×8 en x=16, une barre gauche bleue de 4×8 en x=80 et un triangle vert de huit lignes en x=144. Le défilement final vaut (0,0).

L’image vérifie formes et couleurs sur 16 384 pixels, sprites compris. Les 31 tests d’état couvrent registres, effets d’état/verrou, défilement mémorisé, transferts de 0/255 octets, incréments 1/32, bords, dimensions nulles, tables, attributs complets et les deux palettes. Y=255 est vérifié comme écriture de registre, pas comme image de défilement correcte. Les résultats proviennent de KUROSAKI avec NROM ; le matériel réel n’a pas été testé.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\ppu_intrinsics.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\ppu_intrinsics.nes --no-cache --no-disasm

Read PPUSTATUS; the hardware clears VBlank status and resets the shared write latch.

case "__ppu_read_status":
                    if (!Need(0)) return true;
                    EmitAsm("LDA", Mem(0x2002)); return true;

Effectue la même sélection de banque PRG adaptée au mapper que __bankswitch. Applique les mêmes vérifications et ne rétablit pas automatiquement la banque précédente.

Syntaxe

void __prg_bank_set(u8 bank);

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

Valeur renvoyée

Aucune (void).

Conditions et limites

Un changement persistant de banque ne doit pas rendre inaccessibles le code exécuté ou son adresse de retour. Placez cet appel, bank_switch elle-même si elle est utilisée, et le code qui suit dans la banque commune ou fixe 0, comme dans l’exemple.

L’état de la bibliothèque commence à zéro et ne détecte pas le mappage initial de la cartouche. Initialisez-le avec bank_switch. Les intrinsèques et écritures directes dans le mapper n’actualisent pas cet état distinct ; bank_get_current ne vérifie donc pas le mappage matériel réel.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

__prg_bank_set(1);bank_expect(home1[0]==0xA1,21);
__prg_bank_set(2); // Same mapper helper as __bankswitch.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

bank_switch(2) enregistre et sélectionne d’abord la banque 2. Une commutation directe sélectionne ensuite la banque 1 et lit A1 dans home1, tandis que bank_get_current indique toujours 2 ; après restauration, home2 donne à nouveau B2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Use the same mapper PRG-switch helper as __bankswitch; retain executable code in a valid mapping.

case "__prg_bank_set":
                case "__bankswitch":
                    if (!Need(1)) return true;
                    if (Program.NesMapperProfile.IsSurom512 && TryEvaluateConstant(args[0], out int constantBank) && (constantBank < 1 || constantBank > 30))
                    {
                        Program.Error("error KQFC2603 KQFC-SUROM-BANK-RANGE: {0} constant bank {1} is outside 1..30; common bank 0 is not a switch target.", funcName, constantBank);
                        return true;
                    }
                    _mapperWritingFunctions.Add(_currentFunctionName);
                    Load1(args[0]); EmitAsm("JSR", Abs("__kq_prg_set_bank_a")); return true;

Fait avancer une fois le LFSR de Galois FC partagé sur 16 bits et renvoie le XOR des octets bas et haut mis à jour. Un LFSR est un registre à décalage dont la rétroaction est calculée par XOR ; une graine fixe produit donc une suite d’octets reproductible.

Syntaxe

u8 __rng8(void);

Valeur renvoyée

Un résultat u8 (0–255), après un avancement du générateur partagé. Cela décrit le type et les bornes, pas une équiprobabilité de chaque octet.

Conditions et limites

L’étape FC décale l’état de 16 bits d’un bit vers la droite. Si l’ancien bit de poids faible valait 1, elle applique XOR avec 0xB400 à l’état décalé. L’octet renvoyé est low_byte XOR high_byte, pas l’octet bas brut.

Si les deux octets d’état sont nuls, le tirage suivant remplace l’état par 0xA55A avant le décalage. Ainsi, __rng_seed(0) suivi de __rng8() renvoie 255. L’appel de réglage stocke bien zéro ; le remplacement a lieu lors du tirage.

Ces appels partagent un état persistant. La reproduction exige la même cible, la même graine et le même ordre d’appels, y compris ceux des autres fonctions auxiliaires. Gardez réglage de graine et tirages dans un même contexte d’exécution ; ces vérifications ne prouvent pas la sûreté d’un accès concurrent depuis une interruption.

GB et FC utilisent des algorithmes différents et ne garantissent pas la même suite avec la même graine. Ce sont des générateurs déterministes pour le jeu, pas des sources d’aléa cryptographique. Les tests vérifient le comportement de l’implémentation, pas sa qualité statistique ni sa période.

Exemple d’utilisation

__rng_seed(0x1234);
first=__rng8();second=__rng8();third=__rng8(); // FC sequence: 19, 137, 240.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet exemple lit trois octets FC consécutifs. La graine 0x1234 donne FIRST 00019, SECOND 00137 et THIRD 00240. Ces valeurs montrent l’ordre des appels, pas une fréquence ni une note de qualité aléatoire.

Le programme NROM complet affiche les résultats décimaux en bleu sur noir. FAILED doit indiquer 00000. Le texte est transféré avec le rendu désactivé avant l’activation de l’écran de résultats.

La validation a comparé, pour chaque cas, 32 sorties et huit tirages d’octet suivants à un modèle hôte indépendant : 93 cas GB et 18 cas FC, avec graines constantes ou calculées à l’exécution et limites GB de plage, chance et poids. Les écrans pédagogiques ont été contrôlés après 240 images émulées. Le matériel réel et la qualité statistique n’ont pas été testés.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\rng_core.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\rng_core.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Advance the shared 16-bit LFSR and return the XOR of its two bytes; zero state is reseeded to A55A.

case "__rng8":
                    if (!Need(0)) return true;
                    EmitAsm("JSR", Abs("__rng8"));
                    return true;
                // Far-memory helpers pack the address, bank and length arguments according to their explicit byte/word signatures.

EmitHelperStart("__rng8");
            // 16-bit Galois LFSR: if low bit set, shift right then xor $B400.
            EmitAsm("LDA", Mem(_runtimeRngLoAddress));
            EmitAsm("ORA", Mem(_runtimeRngHiAddress));
            // Replace the all-zero LFSR state with a deterministic nonzero seed before advancing.
            string seeded = NewGeneratedLabel("rng_seeded");
            EmitAsm("BNE", Rel(seeded));
            EmitAsm("LDA", Imm(0x5A));
            EmitAsm("STA", Mem(_runtimeRngLoAddress));
            EmitAsm("LDA", Imm(0xA5));
            EmitAsm("STA", Mem(_runtimeRngHiAddress));
            _assembly.Add(Expr.Make(Tag.Label, seeded));
            EmitAsm("LDA", Mem(_runtimeRngLoAddress));
            EmitAsm("AND", Imm(1));
            EmitAsm("STA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("LSR", Mem(_runtimeRngHiAddress));
            EmitAsm("ROR", Mem(_runtimeRngLoAddress));
            string rngNoXor = NewGeneratedLabel("rng_no_xor");
            EmitAsm("LDA", Mem(_runtimeIntrinsicTmp0Address));
            EmitAsm("BEQ", Rel(rngNoXor));
            EmitAsm("LDA", Mem(_runtimeRngHiAddress));
            EmitAsm("EOR", Imm(0xB4));
            EmitAsm("STA", Mem(_runtimeRngHiAddress));
            _assembly.Add(Expr.Make(Tag.Label, rngNoXor));
            EmitAsm("LDA", Mem(_runtimeRngLoAddress));
            EmitAsm("EOR", Mem(_runtimeRngHiAddress));
            EmitAsm("RTS");

Remplace les deux octets d’état du générateur FC. Réutiliser une graine permet à un test ou une relecture de repartir au même point de la suite pseudo-aléatoire ; cet appel ne fait pas avancer le générateur.

Syntaxe

void __rng_seed(u16 seed);

Paramètres

seed

Graine non signée de 16 bits, de 0 à 65535. Les deux octets sont stockés tels quels. Choisissez et notez la graine avant la suite de tirages de jeu à reproduire.

Valeur renvoyée

Aucune (void).

Conditions et limites

Si les deux octets d’état sont nuls, le tirage suivant remplace l’état par 0xA55A avant le décalage. Ainsi, __rng_seed(0) suivi de __rng8() renvoie 255. L’appel de réglage stocke bien zéro ; le remplacement a lieu lors du tirage.

Ces appels partagent un état persistant. La reproduction exige la même cible, la même graine et le même ordre d’appels, y compris ceux des autres fonctions auxiliaires. Gardez réglage de graine et tirages dans un même contexte d’exécution ; ces vérifications ne prouvent pas la sûreté d’un accès concurrent depuis une interruption.

GB et FC utilisent des algorithmes différents et ne garantissent pas la même suite avec la même graine. Ce sont des générateurs déterministes pour le jeu, pas des sources d’aléa cryptographique. Les tests vérifient le comportement de l’implémentation, pas sa qualité statistique ni sa période.

Exemple d’utilisation

__rng_seed(0x1234);
repeated=__rng8(); // The first byte is 19 again.
__rng_seed(0);
zero=__rng8(); // The next draw uses the FC fallback state and returns 255.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet exemple montre un démarrage FC reproductible et la règle de graine nulle. FIRST et RESEEDED affichent tous deux 00019 pour la graine 0x1234. ZERO SEED affiche 00255 après une graine nulle.

Le programme NROM complet affiche les résultats décimaux en bleu sur noir. FAILED doit indiquer 00000. Le texte est transféré avec le rendu désactivé avant l’activation de l’écran de résultats.

La validation a comparé, pour chaque cas, 32 sorties et huit tirages d’octet suivants à un modèle hôte indépendant : 93 cas GB et 18 cas FC, avec graines constantes ou calculées à l’exécution et limites GB de plage, chance et poids. Les écrans pédagogiques ont été contrôlés après 240 images émulées. Le matériel réel et la qualité statistique n’ont pas été testés.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\rng_core.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\rng_core.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Replace both persistent state bytes. Reusing a seed reproduces the sequence; this is not cryptographic randomness.

case "__rng_seed":
                    return EmitKitaqfcHelperCall(funcName, args, ctx, new[] {2}, "__rng_seed");

EmitHelperStart("__rng_seed");
            EmitAsm("LDA", Mem(CallArgBase));
            EmitAsm("STA", Mem(_runtimeRngLoAddress));
            EmitAsm("LDA", Mem(CallArgBase + 1));
            EmitAsm("STA", Mem(_runtimeRngHiAddress));
            EmitAsm("RTS");

Choisit le masque de rendu allumé ou éteint et attend un changement du compteur NMI. Le masque choisi reste actif après le retour.

Syntaxe

void __rob_flash(u8 bright);

Paramètres

bright

Zéro choisit l’arrêt ; tout octet non nul, y compris 255, choisit l’activation. Ce n’est pas un niveau de luminosité.

Valeur renvoyée

Aucune valeur de retour. Rend la main à l’appelant après les attentes demandées.

Conditions et limites

Incluez intrinsics.h. Le gestionnaire NMI par défaut doit fonctionner et faire avancer son compteur. Si NMI est désactivé ou si un gestionnaire personnalisé ne maintient pas ce compteur, l’attente reste bloquée. Il n’y a aucun délai d’expiration.

La phase allumée met PPUMASK et sa copie logicielle à 0x1E ; la phase éteinte les met à zéro. L’ancien masque n’est pas restauré. Cela modifie ensemble le rendu du fond, des sprites et du bord gauche, ainsi que les réglages de niveaux de gris et d’accentuation des couleurs.

Activer le rendu ne crée pas à lui seul un écran blanc. Fournissez des tuiles et des couleurs claires, avec une couleur de fond sombre pour la phase éteinte. L’exemple utilise des tuiles blanches pleines et un fond noir pour faire clignoter tout l’écran pendant l’opération.

Les attentes comptent les changements du compteur NMI. Le délai jusqu’au premier NMI peut être inférieur à une image. Appelez depuis le code principal, pas depuis une interruption. Une autre routine modifiant le masque de rendu peut perturber le motif.

Ce sont des primitives de masque d’affichage et d’attente. Elles ne génèrent ni préambule de commande robot, ni séquence propre à un appareil, ni accusé de réception. La validation couvre les écritures PPUMASK, les comptes NMI et les pixels dans KUROSAKI ; la réception par un robot physique n’a pas été testée.

Exemple d’utilisation

start=__nmi_ready();
    __rob_flash(1); // Enable rendering and wait for one NMI-counter change.
    rob_result[0]=(u8)(__nmi_ready()-start);
    __rob_flash(0); // Disable rendering; the black backdrop remains visible.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Après exécution, l’écran affiche FLASH WAITS 1, PULSE 3 ON / 2 OFF = 5 et A5 BYTE WAITS 48. Le schéma représente 0xA5 : 1,0,1,0 en haut, puis 0,1,0,1 en bas. Chaque case vaut une attente ; blanc signifie rendu activé, noir désactivé. Un bit 1 comporte quatre cases blanches puis deux noires ; un bit 0, deux blanches puis quatre noires. FINAL MASK 0 et TIMING CHECKS OK indiquent la fin.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\rob_timing.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\rob_timing.nes --no-cache --no-disasm

Set PPUMASK and its shadow to 1E or 00, then wait for an NMI-counter change.
The caller supplies image/palette brightness; rendering enable alone does not create a white screen.

EmitHelperStart("__rob_flash");
            EmitAsm("LDA", Mem(CallArgBase));
            string black = NewGeneratedLabel("rob_black");
            EmitAsm("BEQ", Rel(black));
            EmitAsm("LDA", Imm(0x1E));
            EmitAsm("STA", Mem(_runtimePpuMaskShadowAddress));
            EmitAsm("STA", Mem(0x2001));
            EmitAsm("JSR", Abs("__nmi_wait"));
            EmitAsm("RTS");
            _assembly.Add(Expr.Make(Tag.Label, black));
            EmitAsm("LDA", Imm(0x00));
            EmitAsm("STA", Mem(_runtimePpuMaskShadowAddress));
            EmitAsm("STA", Mem(0x2001));
            EmitAsm("JSR", Abs("__nmi_wait"));
            EmitAsm("RTS");

            // Emit the requested number of enabled frames followed by the requested disabled frames.

Effectue les attentes allumées demandées, puis les attentes éteintes, pour produire une impulsion.

Syntaxe

void __rob_pulse(u8 on_frames, u8 off_frames);

Paramètres

on_frames

Nombre d’attentes de la phase allumée, de 0 à 255. Zéro saute cette phase.

off_frames

Nombre d’attentes de la phase éteinte, de 0 à 255. Zéro saute cette phase. Le total peut atteindre 510 attentes.

Valeur renvoyée

Aucune valeur de retour. Rend la main à l’appelant après les attentes demandées.

Conditions et limites

Si les deux comptes sont nuls, ni le masque ni le minutage ne changent. Toute attente éteinte laisse un masque nul ; une impulsion uniquement allumée laisse 0x1E.

Incluez intrinsics.h. Le gestionnaire NMI par défaut doit fonctionner et faire avancer son compteur. Si NMI est désactivé ou si un gestionnaire personnalisé ne maintient pas ce compteur, l’attente reste bloquée. Il n’y a aucun délai d’expiration.

La phase allumée met PPUMASK et sa copie logicielle à 0x1E ; la phase éteinte les met à zéro. L’ancien masque n’est pas restauré. Cela modifie ensemble le rendu du fond, des sprites et du bord gauche, ainsi que les réglages de niveaux de gris et d’accentuation des couleurs.

Activer le rendu ne crée pas à lui seul un écran blanc. Fournissez des tuiles et des couleurs claires, avec une couleur de fond sombre pour la phase éteinte. L’exemple utilise des tuiles blanches pleines et un fond noir pour faire clignoter tout l’écran pendant l’opération.

Les attentes comptent les changements du compteur NMI. Le délai jusqu’au premier NMI peut être inférieur à une image. Appelez depuis le code principal, pas depuis une interruption. Une autre routine modifiant le masque de rendu peut perturber le motif.

Ce sont des primitives de masque d’affichage et d’attente. Elles ne génèrent ni préambule de commande robot, ni séquence propre à un appareil, ni accusé de réception. La validation couvre les écritures PPUMASK, les comptes NMI et les pixels dans KUROSAKI ; la réception par un robot physique n’a pas été testée.

Exemple d’utilisation

start=__nmi_ready();
    __rob_pulse(3,2); // Three enabled waits, then two disabled waits.
    rob_result[1]=(u8)(__nmi_ready()-start);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Après exécution, l’écran affiche FLASH WAITS 1, PULSE 3 ON / 2 OFF = 5 et A5 BYTE WAITS 48. Le schéma représente 0xA5 : 1,0,1,0 en haut, puis 0,1,0,1 en bas. Chaque case vaut une attente ; blanc signifie rendu activé, noir désactivé. Un bit 1 comporte quatre cases blanches puis deux noires ; un bit 0, deux blanches puis quatre noires. FINAL MASK 0 et TIMING CHECKS OK indiquent la fin.

Programme d’exemple complet

Commande de compilation

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\rob_timing.c -I .\kitaqfc\lib -I .\kitaq-docs\samples --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr -o .\out\rob_timing.nes --no-cache --no-disasm

Run on_frames enabled-mask waits followed by off_frames disabled-mask waits; NMI must advance.

EmitHelperStart("__rob_pulse");
            EmitAsm("LDX", Mem(CallArgBase));
            string onLoop = NewGeneratedLabel("rob_on_loop");
            string offStart = NewGeneratedLabel("rob_off_start");
            _assembly.Add(Expr.Make(Tag.Label, onLoop));
            EmitAsm("CPX", Imm(0));
            EmitAsm("BEQ", Rel(offStart));
            EmitAsm("LDA", Imm(1));
            EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__rob_flash"));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(onLoop));
            _assembly.Add(Expr.Make(Tag.Label, offStart));
            EmitAsm("LDX", Mem(CallArgBase + 1));
            string offLoop = NewGeneratedLabel("rob_off_loop");
            string pulseDone = NewGeneratedLabel("rob_pulse_done");
            _assembly.Add(Expr.Make(Tag.Label, offLoop));
            EmitAsm("CPX", Imm(0));
            EmitAsm("BEQ", Rel(pulseDone));
            EmitAsm("LDA", Imm(0));
            EmitAsm("STA", Mem(CallArgBase));
            EmitAsm("JSR", Abs("__rob_flash"));
            EmitAsm("DEX");
            EmitAsm("BNE", Rel(offLoop));
            _assembly.Add(Expr.Make(Tag.Label, pulseDone));
            EmitAsm("RTS");

            // Choose a four/two or two/four frame pulse pattern for each current high bit.

Encode un octet en huit motifs de clignotement, bit de poids fort en premier. Un 1 utilise quatre attentes allumées et deux éteintes ; un 0, deux allumées et quatre éteintes. Le total est de 48 attentes NMI.

Syntaxe

void __rob_send_byte(u8 pattern);

Paramètres

pattern

Motif de huit bits, de 0 à 255. Pour 0xA5, l’ordre est 1,0,1,0,0,1,0,1. Ce n’est ni un identifiant de canal ni un numéro d’action robot.

Valeur renvoyée

Aucune valeur de retour. Rend la main à l’appelant après les attentes demandées.

Conditions et limites

Le dernier bit se termine lui aussi par des attentes éteintes, laissant PPUMASK et sa copie à zéro. Envoie exactement huit bits, sans marqueur de début ou de fin.

Incluez intrinsics.h. Le gestionnaire NMI par défaut doit fonctionner et faire avancer son compteur. Si NMI est désactivé ou si un gestionnaire personnalisé ne maintient pas ce compteur, l’attente reste bloquée. Il n’y a aucun délai d’expiration.

La phase allumée met PPUMASK et sa copie logicielle à 0x1E ; la phase éteinte les met à zéro. L’ancien masque n’est pas restauré. Cela modifie ensemble le rendu du fond, des sprites et du bord gauche, ainsi que les réglages de niveaux de gris et d’accentuation des couleurs.

Activer le rendu ne crée pas à lui seul un écran blanc. Fournissez des tuiles et des couleurs claires, avec une couleur de fond sombre pour la phase éteinte. L’exemple utilise des tuiles blanches pleines et un fond noir pour faire clignoter tout l’écran pendant l’opération.

Les attentes comptent les changements du compteur NMI. Le délai jusqu’au premier NMI peut être inférieur à une image. Appelez depuis le code principal, pas depuis une interruption. Une autre routine modifiant le masque de rendu peut perturber le motif.

Ce sont des primitives de masque d’affichage et d’attente. Elles ne génèrent ni préambule de commande robot, ni séquence propre à un appareil, ni accusé de réception. La validation couvre les écritures PPUMASK, les comptes NMI et les pixels dans KUROSAKI ; la réception par un robot physique n’a pas été testée.

Exemple d’utilisation