PIA Project

From DDCIDeos
(Redirected from BSP Support PhysicalAlloc)
Jump to navigationJump to search

Description

The Platform Integrator Automation (PIA) project is to enable components to allocate physical addresses, notably RAM, without having to change the BSP to do so. The types of physical memory considered:

  • Platform resources
    • MFS
    • DMA buffers
  • DEOS_FLASH
  • DEOS_RAM, i.e., pool 0 range 0 (p0r0 below).
  • memory pools

The basic idea is to introduce a phase of platform project build that would create/modify:

  1. basecon.hyp (DEOS_RAM and DEOS_FLASH)
  2. platreg.pi.xml (Memory mapped resources and DEOS_RAM pool(s))
  3. mkkfs configuration

The project also considered other steps to remove knowledge from the BSP so that the BSP itself would be less susceptible to changes due to changes in application code, e.g., moving/resizing Network Buffers, or the presence/absence of CFFS.

The basecon.pia.xml and basecon-resources.pia.xml files includes BSP defined platform resource(s) (exception vectors, boot stack, etc.) but no driver or application resources. The basecon.pia.xml also includes a specification of the "unallocated RAM", expressed as a memory pool named UNALLOCATED_RAM. The basecon .pia files take the place of platreg.pi.xml. Consequently if a BSP has a platreg.pi.xml file, then it has not been ported to support PIA.

Every component, that needs a memory mapped resource would provide a .pia declaring its need, and specifying allocationDirection=end. This includes drivers needing DMA buffers, or components like CFFS.

Status

pia has been setup in kismet and works by default for the qemu BSPs as well as the ones noted below. At this point (2023-09-27) most PIA components are still unreleased. 

bdu64
run-docker -it --rm ubuntu-kismet-dev

Create a qemu platform project.

  1. Copy for editing of pia files should work, but OA does not yet prompt for re-hypstart so you must clean and rebuild.

PCRs: Deos DDCI

Tasks

The list below includes components and all active BSPs. The list of components is currently incomplete. Unrelease distribution is kismet.

Task Priority Assignee Contact Unreleased Remarks
pia tool 4 GK AL In Work Tool is operational, but documentation is in bad shape/nonexistent
bsp-common (flash, ram, etc.) 1 AL AL Done PCR:15022
CFFS 99 FA CP
deos-time 2 FA MV Done PCR:15178
integration-tool 1 CF Done PCR:14921 Check pia todo items. Must add pia UG material.
lwip 1 AL JK Done PCR:15027. Should remove from scm/test.
network-standard-apps 99 FA AL No changes identified at this time.
pci-scanner 99
Target Data Loader (tdl) 99 MV
dtsec 4 PZ CP
dvms-mmc-sdhc 4 CP
fec_andretti 4 CP Done
SATA? 4 PZ CP Ask Chris what component this is for.
virtio-net 1 FA MV Done PCR:15036 virtio ethernet driver.
BSP celestial 99
BSP cm-crb 99
BSP come-ctl6 10
BSP crucible 99
BSP imx8 4 PZ AL Done-ish Initial PIA support is released. imx8qm DONE(sales), imx8qm-aarch64 DONE (shaka), imx8qm-a72-aarch64 (shaka)
BSP jacinto7-evm 99
BSP ls1043ardb 5 SA AL In Work
BSP ls10x8ardb 7
BSP nai68ppc2 5 SA Done
BSP qemu-arm 1 FA AL Done
BSP qemu-aarch64 3 FA AL Done
BSP qemu-ppc 2 FA AL Done
BSP qemu-x86 2 FA AL Done
BSP qemu-x86-64 3 FA AL Done
BSP qualcomm-rb5 99
BSP s32v234 99
BSP t10xx 6 PZ AL Done PCR:15210 - Add PIA support for t10xx
BSP t2080rdb 5 SA Done
BSP trickyfish 99
BSP zus 5 IF Done Need to disentangle config components. Includes zcu102, nai-ultrascale

Confirmation

This shell command lists the packages that have PIA files: 

 for f in $(find /desk -iname '*.pia.xml'); do dpkg -S $f; done | cut -f 1 -d: | sort -u

Goals

Dreams:

  1. Eliminate driver and application induced churn in BSPs.
  2. Enable assembling a customer BSP using off the shelf drivers and a base BSP using OpenArbor only
    • I.e., it works that well.
    • Supports testing (at least informal) of the generated BSP.
    • Includes documentation and other "normal" BSP artifacts.
  3. Enable user to do more things without "copy for editing" and eliminate the need to copy more than what is needed.
  4. Reduce the cost of the CVTs
  5. Enable a component, e.g., vfile, to be added to OpenArbor without needing OpenArbor to change.
    • At least for makefile stuff.
  6. Only one reference Boot/PAL for any SOC, perhaps every (related) family of SOCs

Use Cases

  1. Create a child platform that:
    1. Adds a (vfile?) driver
    2. Adds another Ethernet interface (multi-home)
    3. Adds a second lwip instance (multi-network)
    4. Adds an MFS
    5. Changes DEOS_FLASH size
  2. User adds or changes various PI section data.
  3. Change list of periods

Introduce platform integrator automation (PIA) files

OpenArbor uses the existence of basecon.pia.xml as indicator to use pia files when building a platform project.

  1. All .pi "top level" elements are "addable" by a .pia file.
    1. Not only platform resources and pools, but also groups, periods, etc.
    2. pia tool merges all definitions.
  2. Much smaller stuff to copy/modify.
  3. basecon.pia.xml contains only kernelAttributes and platformAttributes.
  4. Mixed bag for users.
    • + Less collateral copy damage
    • - Harder to find item to edit
    • - Getting an editable overview (e.g., complete .pi file) would be a tooling problem.

Issues

ISSUE: what about .fp files that create memory objects? Presume no longer needed (allowed?).

  1. XML file naming convetions:
    1. component.cd.xml
    2. How to represent bus and unit numbers?
    3. Should buffers and registers be in separate .pia files?
  2. Changing resources during development likely will be unreliable until shutdown protocol is implemented.
    • Should be completely solid for "from scrath build and flash board" scenario.
    1. Some changes, e.g., to size of DEOS_FLASH, can't be avoided.
    2. Whether a change requires a re-hyperstart is highly system configuration dependent, e.g., if boot must load the MFSes on a hyp index change.
    3. Changing an MFS that OpenArbor can update via /proc/res may or may not force a re-hyperstart, but recovering from an uninitialized MFS would require support from OpenArbor, e.g., to do a full /proc/res download.
  3. DMA. Changing the physical addresses of a memoryMappedResource supporting DMA would likely lead to a non-functional box after a registry change.
    1. Requiring a consistent memory map across all registries would be hard to manage.
    2. Suggestion is to introduce a DMA shutdown protocol, either in the kernel or at the application level. How is TBD (see #Meeting Notes).
    3. Having a shutdown protocol is key to making this capability reliable during development.
    4. Having assurance that DMA is turned off in all devices is sometimes a (DAL A) customer requirement.
  4. Physical memory layout is even more obtuse until .cck file is viewed.
    • Could have IT output xml format which we could view in OA or browser as either html or graphically.
      • xml stylesheet for tabular HTML would be trivial. svg would be slightly harder.
      • having "source of resource" in .pi and/or report .xml file would enable easier editing of the source input from such a view.
  5. Do we need an OpenArbor option to "use the pi.xml file rather than the pia files? E.g., so the user can manually add striping.
  6. Is there a way to provide some guidance/assurance to OpenArbor that integrating a component "will work before integrating it". E.g., some sort of dependency manager that OpenArbor could use to "grey out" components that won't work.
  7. It would be helpful if the resulting output files contained a comment providing the name of the source .pia file from whence the content originated.
  8. BSP user guide has historically included a physical memory map. That is now dynamic. How should that be addressed?
    1. Proposal: Point at integration tool output.
  9. Derivative BSPs might not have any user guide, how do we ensure the customer looks at the parent platform for cert issues and other guidance?
  10. Does OpenArbor honor debugComponent from .cd.xml files? Yes.
  11. Should OpenArbor automatically include the component that turns on debugComponent for kernel and network? OA includes development-support by default.
    1. Should OpenArbor have a diagnostic and Production platform mode that controls debugComponent for kernel and network?
  12. Should OpenArbor automatically include the component that adds standard apps?
  13. Propose bsp-common component that contains deos-ram flash, bsp-common, debug-components .cd.xml files.
    1. Every BSP would depend on bsp-common.cd.xml.
  14. Have boot and/or PAL for broader range, e.g., all uboot arm processors?
    1. what is parentProject hierarchy?
  15. Assigning ownership of (PIA) resources still requires fp goo. Is there a better way?
  16. Some .pia files are intended to be modified, others not so much. Should we have a "warn on copy for editing" property?
What components would need to be updated
 - (All?) network drivers
 - firewire
 - cffs
 - usb
 - tte
 - dma drivers.
 - all "active" BSPs 10-15

# Spurious re-hyperstart needs to be minimized.

    - having a shutdown hook would resolve need to re-hyp due to
      changes to DMA platform resources.
      Options:
        - register a "shutdown hook" with the PAL.
        - Kernel "unloads" the PRLs.
        - user mode signalling mechanism.
        - What is required assurance level of "no DMA".
      Concerns:
        - latency
        - Need for user mode application interactions before shutdown.
        - Discretionary?
      Affected components:
        - All DMA drivers: network, BSPs, ???
      Proposed Kernel solution: allow prls to register a function the kernel 
      will call when a "shutdown" happens. The following is still TBD: 
        - how these functions are registered
        - what it means to "shutdown" (warmstart, coldstart, mode change)
        - what data needs to be provided to the registered functions

Striping

Current design doesn't include striping support.

TODO: presumably it is ok to continue with basic proposal rather than waiting for this.

  1. Making multi-range striped resources will require user to hand edit .pi file.
  2. Could have platform define "basic stripe" (e.g., smallest block+gap size)
  3. User could define stripe objects in terms of "basic stripe"
  4. platform resources and pools could be defined in terms of stripe objects
  5. Cache Partitioning - Code & Data
    1. Cache partitioning: The alignment of Deos RAM is important to define the partitions.
    2. Two options:
      1. How it works today (e.g., aliasing)
      2. Specify smallest stripe
      3. Note: might need pool definition capability
  6. platform resources:
    1. suggest manual for now (user has to allocate a block then construct stripes within it
    2. Could introduce a stripe object and pass that to allocate.
  7. pools: ???

Extracted from email chain

RLF: My initial goal is the multicore-memory-pools kernel example is supported and OA can update their multicore-integration test (DDCI_PCR:4932). This should just need basic memory pool support, single range per pool. Will pia help with making .hyp settings and registry for pool 0, range 0 consistent?

However, generally would like user to have access to full feature set; multiple ranges in a pool, striping in platform resources, etc.

GK Mostly for my own notes, the task is to modify the pia allocate() function to

  • be aware of associated resource striping.
  • have an algorithm to track/pack multiple stripe requests such that the minimum amount of address range is consumed
  • somehow mix in the other allocate() capabilities related to allocation order.

Proposed Changes

Migration

  1. Update drivers to add .pia support.
    1. support will immediately be active in BSPs with PIA support, but will be ignored by BSPs lacking pia support.
  2. When all the drivers required by a BSP have pia support, convert the BSP.
  1. DAL E components (including drivers): re-release them with .pia support.
    • Should be pretty easy and wouldn't require much if any testing
  2. DAL !E components: two options:
    1. delta-baseline
    2. Add cygwin/linux dependent package (e.g., cffs-config-files) that provides .pia.xml support. When component is next updated, make dependent package empty.


Add PIA support to BSP

The following are the steps to add PIA support to a "legacy" BSP. For reference see the qemu BSPS. All have SCM commits that contain the needed steps.

General constraints:

  1. All .pia files must be Integraion Tool (IT) version 3.62.0 or newer.
  2. If the BSP has both makeboot and PIA support:
    1. It must be makeboot version 2 compatible.
    2. There must be a basecon.makeboot file.

In openarbor.options:

Remove elements: 

 <itFile>platreg.pi.xml</itFile>
 <depend>standard-apps</depend>
 debugComponent (all of them)
 non-bsp specific itFiles, e.g, cffs.fp.xml

Add: 

 <itPiaFile>basecon.pia.xml</itPiaFile>
 <itPiaFile>basecon-resources.pia.xml</itPiaFile>
 <depend>bsp-common</depend>

TODO: Note the qemu BSPs have the virtio ethernet controller in the .options file. It probably should have been in the lwip-platform-specific.cd.xml or virtio-net.cd.xml file instead.

Please use the .options element order defined by the qemu BSPs. I.e., use a diff tool.

TODO: Perhaps DEOS_FLASH should be first+N so that the BSP can add some resources that get allocated before flash?

Remove from basecon.hyp: 

   -platform              Moved to basecon.makeboot or removed if platform doesn't support makekboot.
   -hypFile               Provided by OA.
   -displayName           Moved to basecon.makeboot or removed if platform doesn't support makekboot.
   -DEOS_RAMStart         Now in pia-content.hyp
   -DEOS_numRAMPages      Now in pia-content.hyp
   -DEOS_FLASHStart       Now in pia-content.hyp
   -DEOS_numFLASHPages    Now in pia-content.hyp
   -kernelFile            Would be stripped by OA anway.
   -bootDest.             Provided by OA.

platreg.bangvar.pi.xml:

  1. Update the platreg.banvar.pi.xml to integ tool version 3.62.0 (or newer).
    1. This can be problematic due to the exclamation marks in the bangvar files. Sometimes it is easiest just to diff the newly copied bangvar files against an already converted BSP. Just be sure to set the tool version to 3.62.0.
    2. diff against the installed version of your component in /desk/platform/<component>/etc
      1. if there is no platreg.pi.xml in the etc directory, compare against basecon.pia.xml and basecon-resources.pia.xml (These files contain the elements being separated in this conversion to PIA.)
      2. Keep the bangvars in place for attribute values.
      3. Update all attributes to match the desk files for all name changes, deletions, and additions. The desk version uses the the 3.62 schema, the BSP files need to match the schema once they are updated.
     Examples attribute changes in the tool version schema:
         Name changed:  coldstartThresholdInMs --> coldstartThresholdMs
         Units changed: exceptionLogDWORDs     --> exceptionLogBytes
         Removed:       windowTimerErrorUsec
         Added:         schedulerName
      1. Be aware of any unit changes indicated in attribute name changes and make necessary value conversions, e.g. an attribute changed from inWords to in Bytes.
  2. svn cp platreg.bangvar.pi.xml basecon-resources.bangvar.pia.xml
  3. In basecon-resources.bangvar.pia.xml
    1. Change encoding to UTF-8.
    2. Rename "platform" element to "pia"
    3. Change name to "ANY"
    4. Delete "comment" attribute for the (new) "pia" element (pia XSD does not support comment).
    5. Replace noNamespaceSchemaLocation xsd from pi.xsd to pia.xsd.
    6. Delete all top level elements other than "resources"
    7. (optional) delete unused interrupts.
    8. make sure all physical addresses allocated by the BSP are in memoryMappedResources, e.g., Exceptions, SCATHitmap, TestResults, bootRAM, video, psio, etc.
    9. delete DEOS_RAM and DEOS_FLASH
    10. delete application specific memoryMappedResources, e.g., NetworkBuffers, deos-time, cffs, TIME, TIME_CONTOL, etc.
    11. Remove driver specific buffers.
      1. Exceptions possible if driver is not converted to pia, but only with management buy-in.
    12. Driver specific registers and memoryMappedResources:
      1. put them in a driver specific .pia file.
      2. for memory startAddress value, change it to "allocate()"
      3. for memory lengthInBytes value, use a constant (initially, this may come from the processed xml files in /desk/etc)
      4. Coordinate file name and inclusion of the file by the driver's .cd.xml with the driver.
    13. Add an UNALLOCATED_RAM memoryMappedResource, (bangvars come from constants.py).
         <memoryMappedResource
              name = "UNALLOCATED_RAM"
              startAddress = "!UNALLOCATED_RAMStartPhys!"
              lengthInBytes = "!UNALLOCATED_RAMSizeInBytes!"
              accessRights = "none"
              allowMultipleOwners = "no"
              cacheMode = "writeBack"
              resourceOverlapList = ""
              proxyAccessPermitted = "yes"
            >
         </memoryMappedResource>


  1. svn mv platreg.bangvar.pi.xml basecon.bangvar.pia.xml
  2. In basecon.bangvar.pia.xml:
    1. Change encoding to UTF-8.
    2. Rename "platform" element to "pia"
    3. Delete the "comment" attribute for the (new) "pia" element (pia XSD does not support comment).
    4. Replace noNamespaceSchemaLocation xsd from pi.xsd to pia.xsd.
    5. delete all top level elements other than "platformAttributes" and "kernelAttributes".


If the platform supports makeboot:

  1. svn cp basecon.bangvar.hyp basecon.bangvar.makeboot
  2. Remove all switches that are not intended for makeboot.

If the platform does not support makeboot there is no need for a .makeboot file.


In basecon.bangvar.hyp:

  1. Delete switches: -platform, -displayName, -defaultRegistry, -hypFile, -kernelFile, and -bootDest.
  2. delete DEOS_RAM and DEOS_FLASH related switches, e.g., -DEOS_RAMStart, -DEOS_numRAMPages, -DEOS_FLASHStart, and -DEOS_numFLASHPages
  3. for -memoryRegion retain boot defined memory regions, e.g., Exceptions, ABCHitmap, testResults, psio, CGAVideoMemory, bootRAM, etc.
  4. delete any indirection include of standard-apps.hyp
  5. Diff against the appropriate architecture specific qemu target. Eliminate spurious differences.

makefile.mk: (Check all makefile.mk files for the component)

  1. Delete all .itconf files, including any "eval" calls used to generate itconf files.
  2. delete component specific sections, e.g., cffs
    1. If present, also remove other BSP references, e.g., delete references to cffs from common and README.txt
  3. Update to include newly added bangvar files, any changed file names, and any other files added or removed from the component.

constants.py:

  1. Update to no longer reference any of the deleted items referenced above.
  2. Add an UNALLOCATED_RAM after all the other allocations.
# All the remaining RAM is unallocated.
unallocatedRam = RAM.allocate("UNALLOCATED_RAM", length=region.Auto)

Warning

Some platforms block the memory at the bottom. Given PIA will allocate resources starting from the bottom of UNALLOCATED_RAM, some resources might get assigned to those blocked addresses. The workaround is to avoid that memory by limiting the UNALLOCATED_RAM size. This can be achieved by adjusting the size of all the RAM in the line that reads: "RAM = phys.allocate("RAM", 2*GiB, offset=RAMStartPhys)" in constants.py.

Notes

Detailed Notes, TODO items and more history are at: https://ddci.zapto.org/scm/test/projects/phys-alloc/bsp-phys-alloc-update-steps.txt

  1. Eliminate -kernelFile lines from basecon.hyp
    • test infrastructure which will temporarily take on responsibility for providing -kernelFile info for every active platform
    • test_elfchk. Proposed alternate is a hard coded list of files with likely stable dependencies
    • will be replaced by cdproc ability to process .options and .cd.xml files from command line.
  2. basecon.hyp file now contains only switches destined for hypstart
  3. New basecon.makeboot file now contains only switches destined for makeboot
    • This is a major step to enabling toolCrib.py to generate errors for unknown switches.

Add PIA support to Driver

Drivers install files into platform directories.

parent platforms describe inheritance 

 desk
  etc              -- Drivers would install architecture independent files at this level
  ppc              -- Drivers would install binaries at this level
  platform
    t2080          -- Drivers would install XML for interrupts and registers at this level
    -- The following t2080 "children" would specify <parentPlatformName>t2080</parentPlatformName>
    nai68ppc2    -- lwip.config and truly platform specific files/drivers at this level.
    celestial
    t2080rdb
    nai68ppc2-db

Driver would be comprised of two packages:

  1. Binaries
  2. Configs -- XML files for the boards where the driver is ported.
    1. These might be installed into any of several directories
    2. Having the separate config component is also a strategy to deal with renaming resources.
    3. If the driver is inextricably tied to the BSP, then it is acceptable for the driver's .pia file to be left in the BSP. E.g., virtio drivers addresses can change based on the version of qemu and hence the BSP's version, tracking these changes is problematic.
      1. In the long term it might make sense to have the .pia file in such cases be an output based on something else, e.g., a pci config file.
      • Initially no resource name changes until all BSPs are pia-ified.
      • Once all referencing BSPs are pia-ified, driver can rename resources and release matching driver code.

OpenArbor ignores .pia files unless the BSP contains a basecon.pia.xml file. Consequently, a pia-ified driver's .pia file is ignored and the BSP's definition is used.

Each driver would deliver files named (options): TODO:

  1. the same as the resource name
  2. the component name + resource name
  3. "res-" + resource name


PIA Checklist

Create a PCR for the driver (if one is not already created)

Build the driver in the kismet environment

Fix any errors and warnings

Follow the Get Started section for the 64-bit Port numbers 4-7 - https://deos.ddci.com/ddciWiki/Deos_64-bit_Port

Create a config folder in the mainline directory

  1. Create a platform folder and a etc
  2. Create any platform, parent platform or etc files as needed (example is provided above)
  3. Move any non-platform specific files from code/xml to config/etc
  4. Move any parent platfrom specific files from code/xml to config/platform/$PARENTPLATFORMNAME
  5. Move any platform specific files from code/xml to config/platform/$PLATFORMNAME/etc (you may need to go into parent platform first)
  6. Remove the code/xml folder

Remove the lib from the .fp.xml file name if it exist

  1. Edit the .cd.xml file to reflect this change
  2. Edit the makefile to reflect this change (most likely change $(APPLICATION) to $(APPBASE))
  3. If necessary add .fp.xml files for each platform where it is different, if not leave it in the common config/etc folder

Modify the .cd.xml files to include the PIA file

  • Add <itPiaFile>$COMPONENTNAME.pia.xml</itPiaFile> above <kernelFile>

Add .pia.xml files for each BSP that is used

  • Copy the contents below into the PIA file
 <?xml version = "1.0" encoding="UTF-8"?>
   <pia
     name = "ANY"
     validityKey = "0"
     toolVersion = "3.62.0"
     xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation = "ddci:/xsd/pia.xsd"
   >
     <resources>
       <interrupts>
 
       </interrupts>
       <memoryMappedResources>
 
       </memoryMappedResources>
     </resources>
   </pia>
  1. Add any memory mapped resources and interrupts that are used by the driver from the basecon-resources.pia.xml and the .fp.xml files in the platform project, remove any resources from these files that are moved to the PIA file.
  2. Add these files to any parent platform etc folder or platform etc that they are needed in

Edit the makefile to include the new line that will copy over the contents of the config directory

  • Add the config copy line above "DI_DESK_TARGET_APPBIN += $(APPLICATION_BIN) $(APPLICATION_BIN_DBG)"
 #------------------------------------------------------------------------------
 # Config Copy
 #------------------------------------------------------------------------------
 $(eval $(call INSTALL_TREE,$(DISTRIBUTION_INSTALL_PREFIX),$(BRANCH_PREFIX)/config,\( -iname '*.bangvar.*.xml' \)))
  • Remove the lines that declare the variable for the .cd file and the line adding it to the etc directories

Ex. OA_CD_FILE = duart-nxp.cd.xml, DI_DESK_TARGET_ETC += $(OA_CD_FILE)

  • Remove the line adding vfile to the etc directory

Ex. DI_DESK_TARGET_ETC += $(APPLICATION_VFILE_XML)

Update the configure.ac file to include the directories that should be searched for bangvar files

  • Add the xBranchPrefixSubdirs variable below, above the builtin () line
 # This is needed for the device driver to deliver content from config
 xBranchPrefixSubdirs="code config docs"

Test that the PIA changes work by executing the previous test listed in the FTP server in a platform project where the memory mapped resources and interrupts in the basecon-resources.pia.xml have been removed

Roll the major version number and unrelease the driver


Network Driver PIA Checklist

Work through the steps in the original PIA checklist.

Identify all BSPs that use the network driver. These BSPs must be PIAfied in tandem.

Copy the following files from the BSP to the network drivers appropriate config/platform/etc directory, delete them from the BSP after they are moved Note: If any BSPs share the same .fp or .pia files this may be grounds for a parent platform, reach out to Chris for naming

  • lwip-platform-specific.cd.xml
  • lwip.config

Remove makefile instructions

  • Remove lwip-platform-specific.cd.xml and lwip.config from the makefile confFiles
  • Remove lwip-network.pd.xml from FILE_TO_CLEAN
  • Remove the .itconf section an example is listed below
 #------------------------------------------------------------------------------
 # To support kernel and other components' requirements based test 
 # infrastructure, *.itconf files need to be provided.
 #------------------------------------------------------------------------------

 # Needed by both normal and download mode platform registries.
 itconfCommonFiles = \
                     deos-kernel.fp.xml \
                     dtsec5.fp.xml \
                     libansi.fp.xml \
                     lwip-network.pd.xml

 $(eval $(call make-file-from-list-rule,\
                 $(itconfCommonFiles) \
                 @standard-apps.itconf, \
                 $(config_makefile)))

 $(eval $(call make-file-from-list-rule,\
                 $(itconfCommonFiles) \
                 deos-kernel-download-mode.fp.xml \
                 @standard-apps-download-mode.itconf, \
                 $(config_makefile)))

Create a .pia file in the current config/platform/etc and copy any memory mapped resources or interrupts used by the network driver from basecon-resources.pia to the .pia file, delete these resources and interrupts from basecon-resources after creating the .pia file.

Look in lwip-platform-specific.cd.xml and note the .fp file that it includes. Move this .fp file from where it is stored in the network driver to the current config/platform/etc directory then delete the <itFile>****.fp.xml</itFile> from the file.

Edit the .cd file to include <itFile>****.fp.xml</itFile>. Ensure that the fp file is the same name for all platforms and is combined into a parent platform when they are the same.


BSP PIA Checklist

Remove all interrupts from the basecon-resources file that are not system owned. Interrupts that are system reserved and needed by the board and should be kept (all reserved# interrupts can be removed).

All Memory mapped resources that are not owned by the board should be removed from basecon-resources, most board owned resources are marked with , PCIE can be removed along with GPIO (check to see if GPIO has an accompanying driver)

Move the pcie-scanner-resources.fp.xml file to the appropriate directory in the pcie-scanner component

Remove pcie-scanner-resources.fp.xml from the makefile confFiles

Remove extraneous depends and files from the openarbor.bangvar.options file

  • <itFile>pcie-scanner-resources.fp.xml</itFile>
  • <depend>dvms</depend>

Integ Tool Proposed Changes

IT (or kernel?) would provide default .pia.xml for the .pi.xml content for:

  1. periods
  2. schedulers
    1. TODO[Issue]: The "schedulers" element has content that depends on number of windows and cores, so a "default file" is not practical.
  3. windowActivationTables
  4. usernames
  5. groupnames
  6. files

Currently the IT has default values for these built into the IT. Making them explicit files would make it easier for users to know how to modify the defaults.

  • TODO: OpenArbor copies the output .pi.xml file back to the "copy for editing" version, so it makes it tough to retian the separate file content.
    • Could the pia tool detect missing content and put the defaulted material into a new .pia file (or set of files) in a TBD location (probably directed via a command line switch) in addition to generating the .pi.xml file?

pia tool

.pia.xml file would have nearly the same format as existing IT .pi.xml files: 

   some header goo
      <memoryMappedResources>
         <memoryMappedResource
              name = "CFFS_RAM_RW"
              startAddress="allocate(from=^UNALLOCATED_RAM^)"
              lengthInBytes = "0x2D00000"
              accessRights = "rw"
              allowMultipleOwners = "no"
              cacheMode = "off"
              resourceOverlapList = "CFFS_RAM_RO"
              proxyAccessPermitted="yes"
            >
         <memoryMappedResource
              name = "CFFS_RAM_RO"
              startAddress="startAddress(^CFFS_RAM_RW^)"
              lengthInBytes = "lengthInBytes(^CFFS_RAM_RW^)"
              accessRights = "r"
              allowMultipleOwners = "yes"
              cacheMode = "cacheMode(^CFFS_RAM_RW^)"
              resourceOverlapList = "CFFS_RAM_RW"
              proxyAccessPermitted="yes"
            >

startAddress attribute value can contain a call to allocate() or startAddress(): 

 allocate(aligned=alignment, from=source, priority=pri, direction=dir)

Allocates lengthInBytes contiguous bytes of memory from the 'source' platform resource.

  • alignment is a power of 2. defaults to page size
    • TODO: must alignment be at least page size?
  • from/source is a platform resource name, default is 'UNALLOCATED_RAM'.
  • priority order is first, first+1, ...first+n, default, last-m, ..., last-1, last. The default is 'default'.
    • Priority is expected to be irrelevant for verified components, it is only for development. See #UNALLOCATED_RAM Guidelines below.
    • The mnemonic for first and last is an array: The first element is zero, the second element is 1, i.e., first+1. Similarly for last-n.
  • direction is start | end, default is 'end'.

For each source, allocation is done ordered by: direction('end' first, then 'start'), priority, alignment(larger first), name. If there is an allocation that specifies "remaining()" it is performed last. There can only be one "remaining()" for a given source. 

 startAddress(resource name)

lengthInBytes can be a call to lengthInBytes(), or "remaining()" 

 lengthInBytes(resource name)  returns lengthInBytes of the resource.

remaining() means the associated allocation will consume all remaining memory from the source. TODO: should remaining() take a "minimum amount of space required" argument?

cacheMode can be a call to cacheMode() 

 cacheMode(resource name)
  1. TODO: perhaps cacheMode can/should be removed. Its not really required.

For platformMemoryPoolRange:

startingPhysicalAddress can be allocate() or startAddress() (see above for both)

sizeInPages can be lengthInPages() or "remaining()" 

 lengthInPages(resource name)  lengthInBytes of the resource converted to pages

The purpose of allocationDirection is to minimize changes that would cause a re-hyperstart (e.g., deos_flash) vs those that "might not", e.g. "network buffers" or an MFS.

The OA makefile system incorporates the hypstart and mkkfs switch files into the building of the hypstart and MFS files. Some makefile magic would detect hypstart sensitive changes to the DEOS_RAM and/or DEOS_FLASH and cause OpenArbor to prompt the user to perform a re-hyperstart. Proposed criteria: any change to deos_flash, or a change to deos_ram that affects the starting address or reduces the length to something less than the BootInterfaceStructTYP.numRamPagesToInitialize. This warning could be generated after rebuilding the hypstart image and comparing old with new.


TODO: If a platform resource that was the source of any allocate becomes zero length it is omitted from the .pi file.

UNALLOCATED_RAM Guidelines

The UNALLOCATED_RAM resource has the following guidelines. The guidelines are intended to make development easier and to minimize conflicts between different registries that migh arise when a reboot causes a registry change.

direction=start

For direction=start; the "first" 20 priorities are reserved for the BSP's use (first to first+19). The first 0--9 priorities are reserved for the core BSP. The next 10 priorities are reserved for bsp-common which provides DEOS_FLASH with a priority of first+10, DEOS_RAM pool 0 range 0 with a priority of first+11. (Rationale: due to hypstart dependencies, if DEOS_FLASH or pool 0 range 0 is changed requires re-hyperstart). DEOS_RAM is the last resource allocated and uses all remaining memory.

direction=end

For direction=end; the "first" -- "first+9" are reserved for the platform. "first+10" -- "first+19" priorities are reserved for MFSes. (Rationale: it is helpful to have consistency between registries and it is expected that the set of MFSs would be consistent between registries. Allocating from the opposite ends of UNALLOCATED_RAM also minimizes the likelihood of needing a re-hyperstart if an MFSes size changes.)

DMA resources would be priority "first+20" -- "first+39". (Rationale: DMA comes after MFSs because it is assumed all DMA drivers will utilize the kismet kernel's shutdown protocol to disable DMA between registry changes). TODO: Alternatively, since DMA would be very flexible, perhaps they should be last?

TODO: perhaps we should have some symbolic names, e.g., priority=KFS, DMA

TODO: should lengthInBytes by enhanced to accept: decimal-integer {GiB, MiB, KiB, pages)?

PIA Phase 2

Ideas on the next phase of PIA development.

  1. Software System
    1. The existing OA project structure and XML content requires registries to be specified in a platform project (i.e., a BSP). We need a way to define registries in something that can be deployed on a BSP, not as a BSP. E.g., "an IP router" or "a kernel test".
    2. Idea 1: system-project
      1. Like a normal component, but something that can define registries (perhaps the only thing that can).
      2. Adding a BSP to a system-project creates a binding to something, e.g., a "deployment" (need better name), that is like a current platform-project and means "The system deployed on this BSP".
      3. It would be possible to have a system deployed on many different BSPs at the same time. Think "hello-world" on qemu-{aarch64,arm,ppc,x86,x86-64} all at once.
      4. Not sure if a deployment can have its own deployment specific dependencies, but it seems like it might be necessary
      5. This would make it much easier for tests because the BSP would always be "bare bones".
  2. MFS declaration.
    1. Currently OA gets MFS information from the registry. That is too late to have builds without circular dependencies.
    2. Not sure what is needed in the declaration besides the name.
      1. Perhaps geometry or underlying platform resource?
  3. .pda files
    1. Analogous to .pia files, but for .pd files rather than .pi files.
    2. A potential replacement for (most applications of) .fp.xml files.
    3. A way to specify things that currently require .fp.xml files. E.g., to indicate that the FOO library requires TLS space, define a FOO.pda.xml file that contains a <tlsSpaceInBytes>n</tlsSpaceInBytes>.
    4. Define that for specific elements (perhaps attributes) that there are ways to combine the elements:
      1. If the element is within a container, e.g., pool within logicalMemoryPools or processInstance within processInstances, then all elements are shuffled together as long as the elements do not have duplicates.
        1. Element specfic semantics for what contitues duplicates. E.g., "interrupt name must be unique"
      2. If the element defines a combiner rule then apply that rule.
        1. For example: for tlsSpaceInBytes, it might be "align to size_t then sum",
      3. Otherwise duplicates are errors.
  4. Need to provide .pia files for PI tool defaults.
    1. For users, groups, periods, etc. This establishes preferred names for the xml files and permits a "copy for editing" style to override them.
      1. Also facilitates override by things like the test infrastrucure.
      2. Some restructuring is required. The BSP config component currently has:
        1. platformAttributes probably needs to be broken into "software system" and "hardware" elements.
          1. systemTickUsec probably belongs with periods.
          2. hw attributes seem restricted to pageSizeBytes, architecture, numberOfCores
        2. kernelAttributes
          1. Not clear this should be specified by the BSP
          2. Some attributes in platformAttributes and kernelAttributes seem arbitrarily allocated.
    2. For things that require dynamicly determined content, e.g., schedulers, then unknown. Options:
      1. Leave as is, i.e., the IT generates the content (default)
      2. ???
  5. Change xml tools so that the schema is versioned.
    1. Not really PIA specific.
    2. This would allow upgrades using known valid XML content.
    3. Potentially the ability to retain and edit older XML files and still get GUI help.
GK/MH/AL 2024-04-29 telecon notes:
This xml is processed by cdproc.
   cdproc-makefile generates rules to build the MFS.

Is this a .mfs.xml or .kfs.xml?  Going for kfs.xml

name
  type LFS|MFS
  geometry:
     reference;  Perhaps a definition later, address, size, striping
  files in file system:
     <kernelFile> element
     wildcard of some sort:
       [component-name ] filename pattern (glob or regex?)
  No access controls because that is part of PI data.
  Owners of the file system.
    Should this be here?  In the pd files?  Both?


--------------------------------------------------------------------------------
hyperstart.kfs.xml:
  name basecon;
  type LFS
  files: [low priority] [component_name] [ *.*;

Does the metadata project need a "default search path"?

Each pd file would presumably inherit that search path which would
implicitly define the set of MFS files that the process would own and
auto-mount.

.pda

The following is conceptual. Want a way for a library (feature provider) to specify its integration tool interface in a way that is declarative and familiar, e.g., using .pd.xml elements.

Should this be something that can specify application semantics? E.g., to specify the socket port it defines/uses.

Interface/name of documentation for the feature (e.g., /desk/help/ansi-ug)?

Perhaps this should be a feature provider automator (.fpa)? 

  foo.pda.xml:
  <features>
    <feature name="default">
      <processTemplate>
        ...
	various fields disallowed, e.g., breakAtStartup, crcAtProcessCreation, executeFromRAM...
	mailboxQuota = n                     # quatas sum()
	largestAMOSizeInPages = n            # combines using max()
	addlRamPagesForExecuteOutOfRam = n   # sizeof(libfoo.so .text section)
	tlsSpaceInBytes = n                  # sizeof(libfoo.so TLS section)
	exceptionHandlerProtocolVersion = n  # combine by "must all be the same (or unspecified)"

Interesting cases

"if I could find out whether a feature is used I could avoid this"

  • another quota accounting issue introduced in the vfile-aio feature. Accounted for debug video memory but only if the feature is used. The diagnostic variant of vfile creates the debug video memory regardless of whether the feature is used.

The case of LwIP and its apps. It would be nice of .pda could be used by either the stand-alone FTP executable vs LwIP including the FTP app.

Feature Sets

  1. Can a .pda request a process to use a feature?
  2. Can a .pda define a feature?
  <feature name=...>
    - feature parameters
    - necessity (deonticity?): mandatory, optional
      - mandatory features without parameters could be handled automatically.
      - Unused mandatory features with parameters could be tool detected errors.

    <affected-process (-templates?)
      - specify which process is target of feature: using process or some process name, e.g., lwip.
      - pd content with element values being an expression referring to feature parameters
        - same element/attribute combining rules as above

It would be nice if we had a way to specify application defined things like ANSI's "heap size".

  1. Each pda would specify its heap requirement
  2. ansi would take all of the heap specifications and create an environment variable based on them.

Used Feature Sets

  1. Like with FP today, specify feature set name and parameters.
  2. Also suggest having a "not used feature set" specification to specifically indicate a feature is not desired.
    1. This permits tooling to report "TODO" items.
    2. Could enable wildcard, or tool switch so users could "ignore all" and/or turn off tool warnings.

Design History and Rationale

Design history and more rationale can be found in the history of this page, specifically https://ddci.zapto.org/ddciwiki/index.php?title=BSP_Support_PhysicalAlloc&oldid=54329

Implementation Meetings

Meetings for development/refinement.

Agenda for 2023-05-26 meeting

  1. status
  2. striping required or defer?
  3. schedule and priority for adding pia support
    1. Release of pia tool
    2. order of drivers/components
    3. order of BSPs.
    4. still planning to put driver resources, including registers in separate component.
      1. To ease resource renaming.
      2. Not the worst option even in the long term.
  4. Resolve issues, e.g., pia file naming conventions, for
    1. BSPs
    2. Drivers
  5. There is content that has no clear home.
    1. deos-flash and ram pia files
    2. default content for users, groups, schedulers, etc., that is currently added by integ tool.
    3. content of BSP openarbor.options file still has odd stuff
  6. platform lineage in /desk/platform
    1. Unsure if this should be deferred or not.
  7. Unsure what test impact this all has.
Retrieved from "https://ddci.zapto.org/ddciWiki/index.php?title=PIA_Project&oldid=69451"