.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "PROGENDEF" "1" "December 2018" "0.2.38" "User Commands"
.hy
.SH NAME
.PP
\f[B]progendef\f[] \- extract MCU definitions for use with progen
.SH SYNOPSIS
.PP
\f[B]progendef\f[] \f[B]create\f[] \f[B]\-m\f[] \f[I]MCU\f[]
\f[B]\-t\f[] \f[I]TOOL\f[] \f[B]\-f\f[] \f[I]PROJECT_FILE\f[]
.SH DESCRIPTION
.PP
\f[B]progendef\f[] is used to extract \f[B]progen\f[]\-compatible MCU
definitions from project files generated by supported tool (e.g.\ IAR,
CoIDE).
Once generated, new MCU definitions can be used by \f[B]progen\f[] to
generate project files for other supported tools.
.SH OPTIONS
.TP
.B \-m \f[I]MCU\f[]
target MCU name (generated file will be called MCU.yaml)
.RS
.RE
.TP
.B \-t \f[I]TOOL\f[]
tool that generated project file (uVision, IAR, CoIDE)
.RS
.RE
.TP
.B \-f \f[I]PROJECT_FILE\f[]
embedded project file to extract MCU data from (generated by specified
tool)
.RS
.RE
.SH YAML
.PP
\f[B]progendef\f[] (and \f[B]progen\f[]) uses YAML syntax for
\f[I]TARGETS\f[], \f[I]MCU\f[] and \f[I]TOOL\f[] definitions.
.SH ADDING A NEW TARGET
.PP
\f[B]progendef\f[] extracts the information needed to create a new YAML
MCU definition file.
.PP
A \f[B]progen\f[] target consists of: \- a target YAML file (see
\f[I]TARGETS\f[] section) \- an MCU YAML file (see \f[I]MCU\f[] section)
.PP
Target files can be defined and should be placed inside
project_generator_definitions/target.
MCU files are created by \f[B]progendef\f[].
.SH TARGETS
.PP
To generalize MCUs, there are target definitions available.
The target name does not change based on the tool used.
We provide a dictionary where we can define a target with mcu, for
instance:
.IP
.nf
\f[C]
PROGENDEF_TARGETS\ =\ {
\ \ \ \ \[aq]arch\-ble\[aq]:\ \[aq]mcu/nordic/nrf51\[aq],
}
\f[]
.fi
.PP
Such a project can then use either arch\-ble as a target, or nrf51
(mcu).
.SH MCU
.PP
An MCU record defines the basic information about the mcu and 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 you can use the \f[B]progendef\f[] command to create the YAML
file for you.
.PP
If you are adding a new mcu, please follow the uvision naming policy for
MCUs for consistency.
.IP
.nf
\f[C]
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
\f[]
.fi
.PP
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.
.SH TOOLS
.SS uVision
.PP
There are two supported version of uVision.
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.
.IP
.nf
\f[C]
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
\f[]
.fi
.PP
All information in the code above are from a uVision project.
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.
.PP
So, how do we get all this information for a new mcu?
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.
.PP
Once you have specified all required information, test to build your
project and check if the correct target is set in the uVision project.
.SS IAR
.IP
.nf
\f[C]
\ \ \ \ iar:
\ \ \ \ \ \ \ \ OGChipSelectEditMenu:
\ \ \ \ \ \ \ \ \ \ \ \ state:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-\ LPC1768\ NXP\ LPC1768
\ \ \ \ \ \ \ \ OGCoreOrChip:
\ \ \ \ \ \ \ \ \ \ \ \ state:
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \-\ 1
\f[]
.fi
.PP
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 \f[B]progendef\f[] 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.
.PP
Once you specified all needed information, test to build your project
and check if the correct target is set in the IAR project.
.SS CoIDE
.IP
.nf
\f[C]
\ \ \ \ 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
\f[]
.fi
.PP
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 \f[B]progendef\f[] 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.
.SH EXAMPLES
.PP
An example for creating mcu.yaml for lpc1768, from a project file
lpc1768_blinky.ewp (IAR)
.IP
.nf
\f[C]
progendef\ create\ \-m\ lpc1768\ \-t\ iar\ \-f\ lpc1768_blinky.ewp
\f[]
.fi
.PP
This creates \f[C]lpc1768.yaml\f[] file in the current directory.
This file should be placed in
\f[C]project_generator_definitions/mcu\f[].
There should be a vendor folder, and MCU file inside.
.SH REPORTING BUGS
.PP
Upstream bug tracker:
https://github.com/project\-generator/project_generator_definitions/issues
.SH COPYRIGHT
.PP
Copyright (c) 2015 Martin Kojtal
.SH AUTHOR
.PP
This manual page is based on the progendef documentation.
It was created by Nick Morrott <knowledgejunkie@gmail.com> for the
Debian GNU/Linux system, but may be used by others
.SH SEE ALSO
.PP
\f[B]valinor(1)\f[], \f[B]progen(1)\f[]
.PP
Project Generator examples:
https://github.com/project\-generator/project_generator_mbed_examples