mardi 26 mai 2020

Tribord

Tribord

Starboard est la couche de portage et l'abstraction du système d'exploitation de Cobalt. Il tente d'englober toutes les fonctionnalités spécifiques à la plate-forme que Cobalt utilise réellement, et rien de ce qu'il ne fait pas.

Avis de migration GN

Cobalt et Starboard migrent actuellement du système de construction GYP vers le système de construction GN. Ce fichier Lisez-moi contient des instructions pour les deux systèmes. Pour l'instant, GN n'est pas prêt pour une utilisation générale pour Cobalt / Starboard. Si vous n'êtes pas un développeur Cobalt principal, vous devriez probablement ignorer les sections intitulées «Instructions GN» pour l'instant.

Documentation

Voir src/starboard/docpour une documentation plus détaillée.

Emplacements sources intéressants

Tous les emplacements source sont spécifiés par rapport à src/starboard/(ce répertoire).
  • . - Il s'agit du répertoire racine du projet Starboard et contient tous les en-têtes publics définis par Starboard.
  • examples/ - Exemple de code illustrant divers aspects de l'utilisation de l'API Starboard.
  • stub/- La maison de la mise en œuvre Stub Starboard. Celui-ci contient un starboard_platform.gypfichier qui définit une bibliothèque avec tous les fichiers source nécessaires pour fournir une implémentation Starboard complète pouvant être liée.
  • nplb/ - «No Platform Left Behind», suite de tests de vérification de plate-forme de Starboard.
  • shared/- La maison de tout le code qui peut être partagé entre les implémentations de Starboard. Les sous-répertoires délimitent le code qui peut être partagé entre les plates-formes qui partagent une facette de leur API de système d'exploitation.

Guide rapide pour démarrer un port

I. Énumérer et nommer vos configurations de plate-forme

Avant de démarrer un port Cobalt / Starboard, vous devez d'abord définir les noms canoniques de votre ensemble de configurations de plate-forme. Ceux-ci seront utilisés lors de l'organisation du code pour vos plateformes.
Qu'est-ce qui détermine ce qui entre dans une configuration de plateforme par rapport à une autre? Une configuration de plate-forme a un mappage un à un avec un binaire de production. Donc, si vous devez produire un nouveau binaire, vous aurez besoin d'une nouvelle configuration de plate-forme pour cela.
La convention de dénomination recommandée pour a est:
 -
Où est un nom spécifique à la famille de produits que vous portez sur Starboard et est un ou plusieurs jetons qui décrivent de manière unique les spécificités du binaire que vous souhaitez que cette configuration produise.
Par exemple, supposons que votre entreprise s'appelle BobCo. BobCo utilise plusieurs architectures de périphériques différentes, il devra donc définir plusieurs configurations de plate-forme.
Tous les appareils BobCo sont appelés BobBox, c'est donc un choix raisonnable en tant que produit . Mais ils ont des puces MIPS à la fois grandes et petites. Ils pourraient donc définir deux configurations de plate-forme:
  1. bobbox-mipseb - Pour les appareils MIPS big-endian.
  2. bobbox-mipsel - Pour les appareils MIPS peu endiens.

II. Choisissez un emplacement dans l'arborescence source pour votre port tribord

Pour être parfaitement compatible avec la disposition de l'arborescence des sources de Cobalt, tout code écrit par une partie qui n'est pas l'équipe de Cobalt doit se trouver dans le src/third_party/répertoire. Le choix vous appartient, mais nous vous recommandons de suivre cette pratique, même si, comme nous nous attendons à le faire, vous ne prévoyez pas de partager votre implémentation Starboard avec quelqu'un.
Principalement, le respect de cette convention garantit qu'aucune modification future de Cobalt ou Starboard n'entrera en conflit avec vos ajouts de code source. Starboard est destiné à être une jonction où les nouvelles versions de Cobalt ou les implémentations de Starboard peuvent être remplacées sans changements de code importants (et, espérons-le, tout).
Nous vous recommandons de placer votre code ici dans l'arborescence source:
src / tierce_partie / tribord /  /
Avec des sous-répertoires:
  • shared/ - Pour le code partagé entre architectures au sein d'une famille de produits.
  • /- Pour tout code spécifique à une variante binaire spécifique. Chacun d' entre eux doit au moins avoir configuration_public.h, atomic_public.h, thread_types_public.h, gyp_configuration.py, gyp_configuration.gypiet les starboard_platform.gypfichiers.
Dans l'exemple BobBox de BobCo, nous verrions quelque chose comme:
  • src/third_party/starboard/bobbox/
    • shared/
    • mipseb/
      • atomic_public.h
      • configuration_public.h
      • gyp_configuration.gypi
      • gyp_configuration.py
      • starboard_platform.gyp
      • thread_types_public.h
    • mipsel/
      • atomic_public.h
      • configuration_public.h
      • gyp_configuration.gypi
      • gyp_configuration.py
      • starboard_platform.gyp
      • thread_types_public.h
Etc.

Instructions GN

Chaque /répertoire doit avoir au moins configuration_public.h, atomic_public.h, thread_types_public.h, BUILD.gn, configuration.gniet buildconfig.gni.
Dans l'exemple BobBox de BobCo, nous verrions une arborescence de répertoires comme:
  • src/third_party/starboard/bobbox/
    • shared/
    • mipseb/
      • buildconfig.gni
      • configuration.gni
      • atomic_public.h
      • BUILD.gn
      • configuration_public.h
      • thread_types_public.h
    • mipsel/
      • buildconfig.gni
      • configuration.gni
      • atomic_public.h
      • BUILD.gn
      • configuration_public.h
      • thread_types_public.h

III. Basez votre port sur un port de référence

Vous pouvez commencer par copier des fichiers d'un port de référence vers l'emplacement de votre port. Actuellement, ces ports de référence incluent:
  • src/starboard/stub
  • src/starboard/linux
  • src/starboard/raspi
Le starboard_platform.gypcontient des chemins absolus, donc les chemins seront toujours valides si vous le copiez dans un nouveau répertoire. Vous pouvez ensuite remplacer progressivement les fichiers par de nouvelles implémentations si nécessaire.
Le point de départ le plus propre et le plus simple provient de l'implémentation de référence Stub. Rien ne fonctionnera, mais vous devriez pouvoir le compiler et le lier à votre chaîne d'outils. Vous pouvez ensuite remplacer les implémentations de stub par des implémentations de src/starboard/sharedou vos propres implémentations personnalisées module par module, jusqu'à ce que vous ayez parcouru tous les modules.
Vous pouvez également choisir de copier les ports Desktop Linux ou Raspberry Pi et de travailler en arrière en réparant les choses qui ne compilent pas ou ne fonctionnent pas sur votre plate-forme.
Par exemple, pour bobbox-mipsel, vous pouvez faire:
mkdir -p src / third_party / tribord / bobbox
cp -R src / tribord / stub src / third_party / tribord / bobbox / mipsel
Modifiez les fichiers /comme il convient (vous reviendrez probablement beaucoup à ces fichiers).
Mettez /starboard_platform.gypà jour pour pointer vers tous les fichiers source que vous souhaitez créer en tant que nouvelle implémentation Starboard. L' '<(DEPTH)'expression dans GYP se développe en suffisamment de ../s pour vous emmener dans le src/répertoire de votre arborescence source. Sinon, les fichiers sont supposés être relatifs au répertoire dans lequel se trouve le fichier .gypou .gypi.
Pour utiliser une nouvelle configuration de la plate - forme dans une version, vous devez vous assurer que vous avez gyp_configuration.py, gyp_configuration.gypiet starboard_platform.gypdans leur propre répertoire pour chaque variante binaire, ainsi que les fichiers d' en- tête configuration_public.h, atomic_public.het thread_types_public.h. gyp_cobaltva analyser vos répertoires pour ces fichiers, puis calculer un nom de port en fonction des répertoires entre src/third_party/starboardet vos gyp_configuration.*fichiers. (Par exemple, pour src/third_party/starboard/bobbox/mipseb/gyp_configuration.py, il choisirait le nom de configuration de la plate-forme bobbox-mipseb.)

Instructions GN

Mettez /BUILD.gnà jour pour pointer vers tous les fichiers source que vous souhaitez créer en tant que nouvelle implémentation Starboard. L' //expression dans GN fait référence au src/répertoire de votre arborescence source. Sinon, les fichiers sont supposés être relatifs au répertoire dans lequel se trouve le fichier BUILD.gnou .gni. Le BUILD.gnfichier contient des chemins absolus, donc les chemins seront toujours valides si vous le copiez dans un nouveau répertoire. Vous pouvez ensuite remplacer progressivement les fichiers par de nouvelles implémentations si nécessaire.
Pour utiliser une nouvelle configuration de la plate - forme dans une version, vous devez vous assurer que vous avez BUILD.gn, configuration.gniet buildconfig.gnidans leur propre répertoire pour chaque variante binaire, ainsi que les fichiers d' en- tête configuration_public.h, atomic_public.het thread_types_public.h. La version GN va scanner vos répertoires pour ces fichiers, puis calculer un nom de port basé sur les répertoires entre src/third_party/starboardet vos configuration.gnifichiers. (par exemple pour src/third_party/starboard/bobbox/mipseb/configuration.gni, il choisirait le nom de configuration de la plate-forme bobbox-mipseb.)

IV. Un nouveau port, étape par étape

  1. Copiez récursivement src/starboard/stubvers src/third_party/starboard//. Vous pouvez également envisager de copier à partir d'une autre plate-forme de référence, comme raspi-2ou linux-x64x11.
  2. Dans gyp_configuration.py
    1. Dans la CreatePlatformConfig()fonction, passez votre comme paramètre au constructeur PlatformConfig, comme return PlatformConfig('bobbox-mipseb').
    2. Dans GetVariables
      1. Définissez 'clang': 1si votre chaîne d'outils est bruyante.
      2. Supprimez les autres variables de cette fonction qui ne sont pas nécessaires pour votre plate-forme.
    3. Dans GetEnvironmentVariables, définissez les valeurs du dictionnaire pour pointer vers les analogues de la chaîne d'outils pour la chaîne d'outils de votre plate-forme.
  3. Dans gyp_configuration.gypi
    1. Mettre à jour les noms des configurations et le default_configuration être _pour votre nom de la configuration de la plate - forme, où est l' une debug, devel, qa, gold.
    2. Mettez à jour vos variables de plateforme.
      1. Réglez 'target_arch'à votre architecture: 'arm', 'ppc', 'x64', 'x86','mips'
      2. Définissez 'target_os': 'linux'si votre plateforme est basée sur Linux.
      3. Définissez 'gl_type': 'system_gles2'si vous utilisez l'implémentation du système EGL + GLES2.
      4. Réglez 'in_app_dial'sur 1ou 0. Cela active ou désactive le serveur DIAL qui s'exécute à l'intérieur de Cobalt, uniquement lorsque Coblat est en cours d'exécution. Vous ne voulez pas de DIAL intégré à l'application si vous disposez déjà d'un support DIAL à l'échelle du système.
    3. Mettez à jour vos indicateurs et bibliothèques de ligne de commande de la chaîne d'outils. Assurez-vous de ne pas assumer une disposition de poste de travail particulière, car elle sera probablement différente pour quelqu'un d'autre.
    4. Mettez à jour les définitions globales dans 'target_defaults'.'defines', si nécessaire.
  4. Parcourez configuration_public.het ajustez toutes les valeurs de configuration en fonction de votre plate-forme.
  5. Mettez starboard_platform.gypà jour pour pointer vers tous les fichiers source que vous souhaitez créer dans le cadre de votre nouvelle implémentation Starboard (comme mentionné ci-dessus).
  6. Mettez à jour atomic_public.het, thread_types_public.hsi nécessaire, pour pointer vers les implémentations partagées ou personnalisées appropriées.
Vous devriez maintenant pouvoir exécuter gyp avec votre nouveau port. Depuis votre src/annuaire:
$ cobalt / build / gyp_cobalt -C debug bobbox-mipseb
$ ninja -C out / bobbox-mipseb_debug nplb
Cela tentera de créer la suite de tests «Aucune plate-forme laissée pour compte» avec votre nouvelle implémentation Starboard, et vous êtes prêt à commencer le portage!

Instructions GN

Suivez la liste ci-dessus, sauf:
  1. Ignorez les étapes sur gyp_configuration.pyet gyp_configuration.gypi.
  2. Mettre à jour BUILD.gnau lieu de starboard_platform.gyp.
  3. Aussi dans BUILD.gn:
    1. Mettez à jour vos indicateurs et bibliothèques de ligne de commande de chaîne d'outils, pour toutes les configurations ainsi que pour chaque configuration individuelle.
    2. Implémentez des configurations de compilateur génériques telles que sb_pedantic_warningset rtti.
    3. Si vous n'utilisez pas une chaîne d'outils prédéfinie, définissez-en une.
  4. Dans buildconfig.gni:
    1. Si votre plate-forme est basée sur Linux, définissez target_os_ = "linux".
    2. Réglez target_cpu_votre architecture cible (par exemple arm, ppc, x64, x86, mips).
    3. Définissez les chaînes d'outils cible et hôte. Si vous avez défini une chaîne d'outils cible dans BUILD.gn, vous voudrez la définir sur cela.
  5. Dans configuration.gni, définissez les valeurs par défaut spécifiques à la plate-forme pour toutes les variables qui doivent être remplacées pour votre plate-forme Starboard. Vous pouvez trouver une liste de ces variables sur //cobalt/build/config/base.gniet //starboard/build/config/base.gni.
Vous devriez maintenant pouvoir exécuter GN avec votre nouveau port. Depuis votre src/annuaire:
$ gn args out / bobbox-mipseb_debug
Un éditeur s'ouvrira. Tapez dans l'éditeur:
cobalt_config = "debug"
target_platform = "bobbox-mipseb"
Enregistrez et fermez l'éditeur. Ensuite, exécutez
$ ninja -C out / bobbox-mipseb_debug nplb
Cela tentera de créer la suite de tests «Aucune plate-forme laissée pour compte» avec votre nouvelle implémentation Starboard, et vous êtes prêt à commencer le portage!

Ordonnance de mise en œuvre suggérée

Lorsque vous lancez une nouvelle plate-forme Starboard, il est suggéré d'essayer de faire passer les tests NPLB module par module. En raison des dépendances entre les modules, il vous sera plus facile de faire passer certains modules plus tôt que d'autres modules.
Voici un ordre d'implémentation du module recommandé dans lequel faire avancer les choses (toujours soumis à des changements importants en fonction des commentaires):
  1. Configuration
  2. main (), Application et Event Pump (c'est-à-dire l'appel dans SbEventHandle)
  3. Mémoire
  4. Échange d'octets
  5. Temps
  6. Chaîne / Caractère / Double
  7. Journal
  8. Fichier
  9. Annuaire
  10. Système
  11. Atomique
  12. Fil et types de fil
  13. Mutex
  14. Variable de condition
  15. Une fois que
  16. Prise
  17. SocketWaiter
  18. Fenêtre
  19. Contribution
  20. Blitter (le cas échéant)
  21. Récepteur audio
  22. Lecteur multimédia
  23. DRM
  24. Fuseau horaire
  25. Utilisateur
  26. Espace de rangement
Publié par à