PROGENDEF(1)

📦
version 0.2.46 · 4 versions
, in debian trixie, ubuntu noble, ubuntu questing

💖 PROGENDEF 💖

okay bestie, so this is the manual page for progendef, from the User Commands crew. sit down, grab a strawberry drink 🍓, and let's get into it.

✨ NAME ✨

progendef — extract MCU definitions for use with progen

like, it pulls MCU definitions out so progen can use them. the whole point. no cap. 💅

✨ SYNOPSIS ✨

progendef create -m MCU -t TOOL -f PROJECT_FILE

that's the whole vibe. one command, three flags, infinite possibilities ✨

✨ DESCRIPTION ✨

so progendef is the girl who goes into project files made by supported tools (think IAR, CoIDE 👀) and extracts progen-compatible MCU definitions out of them. once she's done generating, those brand-new MCU definitions can be used by progen to generate project files for other supported tools. it's giving glow-up, it's giving translation, it's giving interoperability 🦋

✨ OPTIONS ✨

  • -m MCU — the target MCU name, and heads up, the generated file is gonna be called MCU.yaml (yes, named after it, cute right)
  • -t TOOL — which tool made the project file you're feeding in: uVision, IAR, or CoIDE
  • -f PROJECT_FILE — the embedded project file to extract MCU data from, and it must have been generated by the tool you named with -t

✨ YAML ✨

progendef (and progen, her bestie) uses YAML syntax for TARGETS, MCU and TOOL definitions. yaml girlies rise up 🎀

✨ ADDING A NEW TARGET ✨

progendef extracts the information needed to create a new YAML MCU definition file. literally her whole job.

a progen target consists of:

  • a target YAML file (peep the TARGETS section)
  • an MCU YAML file (peep the MCU section)

target files can be defined and should be placed inside project_generator_definitions/target. MCU files are created by progendef. so she makes the MCU ones, you place the target ones. teamwork 🫶

✨ TARGETS ✨

to generalize MCUs, there are target definitions available. and here's the thing — the target name does not change based on the tool used. it stays the same, periodt.

we provide a dictionary where we can define a target with mcu, for instance:

PROGENDEF_TARGETS = {
    'arch-ble': 'mcu/nordic/nrf51',
}

such a project can then use either arch-ble as a target, or nrf51 (mcu). both. either. main character energy honestly 👑

✨ MCU ✨

an MCU record defines the basic information about the mcu plus the specific settings for each tool. the example below shows the uvision settings for the lpc1768 mcu. these specific data can either be manually extracted from a project file, or — and this is the slay part — you can use the progendef command to create the YAML file for you 💅

if you are adding a new mcu, please follow the uvision naming policy for MCUs for consistency. it's the rules, bestie.

mcu:
    vendor:
        - nxp
    name:
        - lpc1768
    core:
        - cortex-m3
tool_specific:
    uvision:
        TargetOption:
            Device:
                - LPC1768
            Vendor:
                - NXP
            Cpu:
                - IRAM(0x10000000-0x10007FFF) IRAM2(0x2007C000-0x20083FFF) IROM(0-0x7FFFF) CLOCK(12000000) CPUTYPE("Cortex-M3")
            FlashDriverDll:
                - UL2CM3(-O463 -S0 -C0 -FO7 -FD10000000 -FC800 -FN1 -FF0LPC_IAP_512 -FS00 -FL080000)
            DeviceId:
                - 4868
            SFDFile:
                - SFD\NXP\LPC176x5x\LPC176x5x.SFR

the data given in the mcu and target definitions use lowercase. the files are stored within this directory for consistency. tool-specific data follows the tools definitions.

✨ TOOLS ✨

✨ uVision ✨

there are two supported versions of uVision, okay. uvision (defaults: uvision4) and uvision5. uVision 5 uses software packs, and it is compatible with the older version via legacy devices. define legacy device as uvision/uvision4.

tool_specific:
    uvision:
        TargetOption:
            Device:
                - LPC1768
            Vendor:
                - NXP
            Cpu:
                - IRAM(0x10000000-0x10007FFF) IRAM2(0x2007C000-0x20083FFF) IROM(0-0x7FFFF) CLOCK(12000000) CPUTYPE("Cortex-M3")
            FlashDriverDll:
                - UL2CM3(-O463 -S0 -C0 -FO7 -FD10000000 -FC800 -FN1 -FF0LPC_IAP_512 -FS00 -FL080000)
            DeviceId:
                - 4868
            SFDFile:
                - SFD\NXP\LPC176x5x\LPC176x5x.SFR

all information in the code above are from a uVision project. and listen — all attributes need to be filled in, in order to get a proper working target in the project file and the correct flash algorithms for the target. no skipping, no shortcuts, no "eh it's probably fine" 🙈

so, how do we get all this information for a new mcu? okay so: we create a new project in uVision, select your target, and save the project. then open the project in a text editor, and look for attributes inside TargetOption, as Device, Vendor, etc.

once you have specified all required information, test to build your project and check if the correct target is set in the uVision project. test it. for real. fr fr.

✨ IAR ✨

iar:
    OGChipSelectEditMenu:
        state:
            - LPC1768 NXP LPC1768
    OGCoreOrChip:
        state:
            - 1

in the code above, LPC1768 is defined. to add a new target, create a new project in IAR, select your desired target, save the project. then either use progendef to extract information or manually open the project in a text editor, and find the attribute OGChipSelectEditMenu. OGCoreOrChip should be set to 1, as Chip will be used.

be careful with OGChipSelectEditMenu, as it should be exact as in origin project. exact exact. character-for-character exact. she does not do typos 💀

once you specified all needed information, test to build your project and check if the correct target is set in the IAR project.

✨ CoIDE ✨

coide:
coide:
    Device:
        manufacturerId:
            - 7
        manufacturerName:
            - NXP
        chipId:
            - 165
        chipName:
            - LPC1768
    DebugOption:
        defaultAlgorithm:
            - lpc17xx_512.elf
    MemoryAreas:
        IROM1:
            name:
                - IROM1
            size:
                - 0x00080000
            startValue:
                - 0x00000000
            type:
                - ReadOnly
        IRAM1:
            name:
                - IRAM1
            size:
                - 0x00008000
            startValue:
                - 0x10000000
            type:
                - ReadWrite
        IROM2:
            name:
                - IROM2
            size:
                - 0x0
            startValue:
                - 0x0
            type:
                - ReadOnly
        IRAM2:
            name:
                - IROM2
            size:
                - 0x00008000
            startValue:
                - 0x2007C000
            type:
                - ReadWrite

LPC1768 MCU is defined above for CoIDE. to add a new target, create a new project in CoIDE, select your target, save the project. then either use progendef to extract information or manually open the project file (.coproj) in a text editor, and search for all the information which is above. it's required to set the target properly. there is information about ROM/RAM sizes, Flash algorithm used and Id numbers for the target. that's the whole package bestie 🎁

✨ EXAMPLES ✨

an example for creating mcu.yaml for lpc1768, from a project file lpc1768_blinky.ewp (IAR):

progendef create -m lpc1768 -t iar -f lpc1768_blinky.ewp

this creates lpc1768.yaml file in the current directory. this file should be placed in project_generator_definitions/mcu. there should be a vendor folder, and MCU file inside. vendor folder + MCU file, that's the nesting situation, don't forget it 💖

✨ REPORTING BUGS ✨

upstream bug tracker: https://github.com/project-generator/project_generator_definitions/issues

found a bug? tell the upstream girlies, not me 😭

Copyright (c) 2015 Martin Kojtal

✨ AUTHOR ✨

this manual page is based on the progendef documentation. it was created by Nick Morrott <nickm@debian.org> for the Debian GNU/Linux system, but may be used by others. iconic of him honestly 🫶

✨ SEE ALSO ✨

and that's the whole page bestie!! this one's version 0.2.46, dated November 2019 — go forth and extract those MCU definitions, you absolute legend 👑✨💅

📦 where this page comes from