Create Pack Datasheet

[ReinhardKeil]

The Problem To Be Solved

From a users perspective it is hard to understand:

• what is the purpose of a software pack
• what components are available in a pack
• what other packs will be required, what are the external dependencies (external APIs)
• which devices or processors are supported by a software pack
• what configuration files are available
• are there any user code templates that help
• what header files define the API of the software component

Suggest A Solution

Add a command to csolution for example data to create the data of all used packs. For example:

csolution data --filter CMSIS           # create data for packs that have CMSIS in their name
csolution data myname.csolution.yml     # create data for the packs in my project

For each pack a file with the name <pack-name>.yml should be created that contains the information about the pack.

Example: https://github.com/Open-CMSIS-Pack/lwIP/blob/main/lwIP.lwIP.pdsc (slightly changed: lwIP.lwIP.pdsc.txt)

Datasheet file: lwIP.lwIP.pack.yml

pack-data:
  pack: lwIP::lwIP@2.2.0                                           # lwIP is a light-weight implementation of the TCP/IP protocol suite
  overview: overview/lpip.readme.md
  license: <unknown>
  keywords: TCP/IP, network, IP connectivity, ethernet             # note: these are missing in PDSC

  devices:                                                         # works with this devices (only when present)
    - device: <condition>                                          # list of devices derived from conditions

  boards:                                                          # works with this boards (only when present)
    - board: <condition>                                           # list of boards derived from conditions

  processors:                                                      # works with this processors (only when present)
    - core: <condition>                                            # list of processor cores derived from conditions

  documentation:
    - doc: lwip/doc/doxygen/output/index.html                      # lwIP::Network&lwIP

  components:
    - component: lwIP::Network&lwIP:API                            # Network high-level wrapper API

    - component: lwIP::Network&lwIP:CORE&IPv4                      # Network Core (IPv4)
    - component: lwIP::Network&lwIP:CORE&IPv4/IPv6                 # Network Core (IPv4/IPv6)
    - component: lwIP::Network&lwIP:CORE&IPv6                      # Network Core (IPv6)

    - component: lwIP::Network&lwIP:RTOS&CMSIS-RTOS2               # OS abstraction layer (CMSIS-RTOS2)
    - component: lwIP::Network&lwIP:RTOS&FreeRTOS                  # OS abstraction layer (FreeRTOS)

    - component: lwIP::Network&lwIP:Driver:Ethernet&CMSIS Driver   # Ethernet Interface using CMSIS Ethernet Driver
    - component: lwIP::Network&lwIP:Driver:SIO&CMSIS Driver        # Serial I/O Interface using CMSIS USART Driver

    - component: lwIP::Network&lwIP:Interface:Ethernet             # Network Ethernet Interface
    - component: lwIP::Network&lwIP:Interface:PPP                  # Network PPP over Serial Interface
    - component: lwIP::Network&lwIP:Interface:SLIP                 # Network SLIP Interface

  header:                                                          # API headers for user code
    - include: lwip/udp.h                                          # UDP Socket Interface (lwIP::Network&lwIP:CORE&IPv4)
    - include: lwip/socket.h                                       # BSD Socket Interface (lwIP::Network&lwIP:CORE&IPv4)

    - include: lwip/udp.h                                          # UDP Socket Interface (lwIP::Network&lwIP:CORE&IPv4/IPv6)
    - include: lwip/socket.h                                       # BSD Socket Interface (lwIP::Network&lwIP:CORE&IPv4/IPv6)

    - include: lwip/udp.h                                          # UDP Socket Interface (lwIP::Network&lwIP:CORE&IPv6)
    - include: lwip/socket.h                                       # BSD Socket Interface (lwIP::Network&lwIP:CORE&IPv6)

                                                                   # Note: when different variants expose the same a list may be condensed
    - include: lwip/udp.h                                          # UDP Socket Interface (lwIP::Network&lwIP:CORE)
    - include: lwip/socket.h                                       # BSD Socket Interface (lwIP::Network&lwIP:CORE)

  templates:
    - file: <name>                                                 # <select> (<component>)

  configuration:
    - file: rte/config/lwipopts.h                                  # lwIP::Network&lwIP:CORE&IPv4
    - file: rte/config/lwipopts.h                                  # lwIP::Network&lwIP:CORE&IPv4/IPv6
    - file: rte/config/lwipopts.h                                  # lwIP::Network&lwIP:CORE&IPv6

    - file: ports/cmsis-driver/config/ethif_config.h               # Driver:Ethernet&CMSIS Driver

  requirements:
    - component: CMSIS:RTOS2                                       # required-by: lwIP::Network&lwIP:RTOS&CMSIS-RTOS2 
    - component: RTOS&FreeRTOS:Core                                # required-by: IP::Network&lwIP:RTOS&FreeRTOS

    - component: CMSIS Driver:Ethernet
      required-by:
        - component: Driver:Ethernet&CMSIS Driver

    - component: CMSIS Driver:Ethernet MAC
      required-by:
        - component: Driver:Ethernet&CMSIS Driver

    - component: CMSIS Driver:Ethernet PHY
      required-by:
        - component: Driver:Ethernet&CMSIS Driver

  examples:
    ...

[ReinhardKeil]

See also https://github.com/Open-CMSIS-Pack/Open-CMSIS-Pack-Spec/issues/260