HSB IP Def Skill

Purpose

Utilisez cette skill à travers quatre workflows :

• Générer un fichier HOLOLINK_def.svh à partir des exigences validées du board.
• Valider un fichier def existant avec le validateur fourni.
• Expliquer / Raisonner sur les macros HSB IP, la légalité et les ports pilotés par macros.
• Comparer deux fichiers def sémantiquement.

Scope

Cette skill possède le contenu de HOLOLINK_def.svh : directives \define, tableauxlocalparam, le wrapperHOLOLINK_pkget la séquence boot-timeinit_reg[]. Le wrapper top-level environnant est possédé parhsb-ip-create-top; la dérivation du profil packetizer uniquement peut être déléguée àhsb-ip-packetizer`.

Le fichier doit utiliser la garde standard plus le wrapper package HOLOLINK_pkg. Chargez references/macro-reference.md pour le wrapper complet et la sémantique par macro.

Prérequis

• Python 3.9+ est requis pour les scripts fournis ; PyYAML est requis lors de la lecture de profils YAML.
• L'utilisateur doit confirmer les écritures de fichiers et les commandes shell sauf s'il a déjà demandé cette opération exacte.
• Un chemin de fichier def concret, du contenu collé ou un profil de génération confirmé est requis avant la validation ou la génération appuyée par script.
• La source HSB IP live est facultative mais préférée lors de la validation par rapport à une révision IP spécifique.

Instructions

• Exécutez le preflight du script fourni depuis references/script-usage.md avant Generate, Validate, Compare ou des vérifications de légalité appuyées par script.
• Ne définissez jamais silencieusement une macro lors de Generate. Montrez la valeur proposée ou l'exigence déduite et obtenez la confirmation de l'utilisateur.
• Posez une question de requirements par tour lors de Generate piloté par chat.
• Utilisez un langage agnostique aux capteurs sauf si l'utilisateur dit que le design est spécifique à la caméra.
• Évitez les affirmations non supportées « typique », « courant », « la plupart des designs » ou basées sur la fréquence de corpus. Ancrées les choix au comportement IP, aux contraintes documentées ou aux requirements utilisateur.
• Surfacez toujours les avertissements footgun HD-W3xx, même quand l'utilisateur pose des questions uniquement sur les erreurs.
• Ne générez pas FPGA_top.sv ; proposez un handoff à hsb-ip-create-top après la validation d'un fichier def généré.
• Traitez les macros non familières comme spécifiques au projet sauf si elles sont documentées dans les références de cette skill ou la source HSB IP live.

Considérations de sécurité

Cette skill peut lire et écrire des fichiers locaux et exécuter des commandes shell via ses scripts fournis. Avant d'exécuter une commande ou d'écrire un fichier, énoncez la commande ou le chemin et obtenez la confirmation de l'utilisateur sauf si l'utilisateur a déjà explicitement demandé cette opération exacte. Pour le contenu HOLOLINK_def.svh collé, écrivez uniquement dans un fichier temporaire isolé généré de manière sécurisée et supprimez-le après la validation sauf si l'utilisateur demande à le conserver.

Version, compatibilité et source live

Cette skill cible la révision HSB IP 16'h2604 et est rétro-compatible avec 16'h2603. La source HSB IP live remplace les références fournies.

Quand le comportement sensible à la source importe :

1. Localisez <hsb-ip-root>/top/HOLOLINK_top.sv. Les racines connues incluent hw/nvcpu_dgx_fpga/vrtl/hololink/ et la release publique fpga/nv_hsb_ip/.
2. Lisez HOLOLINK_REV et HOLOLINK_BACKWARD_COMPAT_REV.
3. Fiez-vous à la source live pour les macros consommées, les portes de port et le comportement RTL quand cela diffère des références fournies.
4. Passez --ip-source <root> à scripts/validate_def.py lors de la validation par rapport à une racine source connue.

Baseline de documentation publique :

• https://github.com/nvidia-holoscan/holoscan-sensor-bridge/blob/release-2.6.0-EA/docs/user_guide/ip_integration.md
• https://github.com/nvidia-holoscan/holoscan-sensor-bridge/blob/release-2.6.0-EA/docs/user_guide/port_description.md

Workflow Decision

1. Generate quand l'utilisateur demande de créer, scaffolder, brouillonner, concevoir ou produire un HOLOLINK_def.svh.
2. Validate quand l'utilisateur demande de linter, vérifier, valider ou réviser un HOLOLINK_def.svh.
3. Explain / Reason quand l'utilisateur demande ce qu'une macro fait, si une combinaison est légale, pourquoi la validation échoue ou comment une macro affecte HOLOLINK_top.
4. Compare quand l'utilisateur demande de differ deux fichiers def ou comprendre ce qui a changé entre les configurations.

Generate

Chargez references/generate-workflow.md et references/script-usage.md.

Suivez le workflow Generate détaillé dans la référence : exécutez preflight, classifiez les requirements fournis, posez une question de requirements par tour, construisez un profil YAML plat, exécutez scripts/generate_def.py, montrez la provenance des champs générés et proposez un handoff à hsb-ip-create-top.

Quand des champs packetizer sont nécessaires, invoquez hsb-ip-packetizer avec le RX count connu, les RX widths et la description de manipulation de données de l'utilisateur. Consommez uniquement les clés YAML packetizer_profile_overlay de cette skill, fusionnez-les dans le profil en cours et continuez la génération et la validation de fichier complet ici.

Validate

Chargez references/script-usage.md. Chargez references/validation-rules.md uniquement quand vous expliquez des IDs de règles spécifiques ou le comportement de validation.

Étapes :

1. Exécutez le preflight du script fourni une fois par session.
2. Localisez le fichier. Si l'utilisateur colle du contenu, dites-lui le chemin temporaire généré avant d'écrire, demandez la confirmation, utilisez un chemin temp sécurisé isolé et nettoyez-le après la validation sauf s'il demande à le conserver. Sinon, utilisez le chemin fourni.
3. Exécutez <PY> scripts/validate_def.py <path> --json et ne réimplémentez pas la validation en contexte.
4. Groupez les résultats par sévérité : erreurs, avertissements, puis info. Pour chaque erreur, citez l'ID de règle, le numéro de ligne et la macro si disponible.
5. Surfacez toujours les avertissements footgun, spécialement les avertissements de silent-fallback HD-W3xx.
6. Si propre, confirmez l'archétype déduit et la version IP, puis suggérez la vérification suivante probable ou le handoff.

Explain / Reason

Chargez uniquement la référence nécessaire pour la question :

Pour les questions de légalité fondées, exécutez preflight et préférez valider un fichier concret ou un fichier synthétique minimal avec scripts/validate_def.py plutôt qu'un raisonnement manuel. Citez les plages de lignes RTL depuis les références quand vous expliquez pourquoi une règle existe.

Compare

Chargez references/script-usage.md, exécutez preflight, puis utilisez <PY> scripts/compare_defs.py <a.svh> <b.svh> [--json|--text]. Résumez les différences sémantiques, pas les changements d'espace blanc ou de commentaire uniquement.

Limitations

• Ne générez pas FPGA_top.sv ; utilisez hsb-ip-create-top après la validation du fichier defs.
• Ne dérivez pas les ensembles de champs packetizer uniquement ici quand le comportement packetizer est sous-spécifié ; déléguez cette tranche à hsb-ip-packetizer.
• Ne traitez pas les archetypes fournis ou les métadonnées de corpus comme des normes. Ce sont des exemples et des métadonnées de maintenance, pas des défauts.
• N'acceptez pas silencieusement les macros inconnues comme comportement HSB IP validé sauf si la source live ou les références les documentent.

Troubleshooting

• Le preflight du script échoue : signalez le requirement Python ou PyYAML manquant et arrêtez-vous avant la génération ou la validation.
• La validation signale des erreurs : groupez par sévérité, citez l'ID de règle et la ligne, et corrigez le fichier defs avant de proposer le handoff top-level.
• La validation signale des avertissements HD-W3xx : surfacez-les même s'il n'y a pas d'erreurs car ils décrivent les risques de silent RTL fallback.
• Une macro inconnue apparaît : traitez-la comme spécifique au projet sauf si la source HSB IP live ou les références fournies la documentent.

Available Scripts

Utilisez <PY> sélectionné lors du preflight depuis references/script-usage.md pour chaque commande.

Bundled Resources

Examples

• Utilisez hsb-ip-def pour générer un HOLOLINK_def.svh pour un nouveau HSB board. Traitez comme Generate, exécutez script preflight, classifiez les requirements fournis, posez une question de requirements par tour et exécutez scripts/generate_def.py uniquement après la confirmation du profil.
• Utilisez hsb-ip-def pour valider mon HOLOLINK_def.svh existant et dites-moi si des avertissements sont importants. Traitez comme Validate, demandez ou localisez le fichier, exécutez scripts/validate_def.py <path> --json, groupez les résultats par erreurs, avertissements et info, et surfacez toujours les avertissements footgun HD-W3xx.
• Utilisez hsb-ip-def pour expliquer si HOST_WIDTH=512 et PTP_CLK_FREQ=90_000_000 est légal. Traitez comme Explain / Reason, préférez une vérification appuyée par validateur concret au raisonnement manuel, et chargez uniquement la référence macro ou validation nécessaire pour expliquer le résultat.