5.6.4 xc-dsc-ld (DSC Linker)

A subset of command-line options may be specified in MPLAB X IDE. Select a category and then set up linker options. For additional options, see the “MPLAB® XC-DSC Assembler, Linker and Utilities User’s Guide” (DS-50003590). See also “Options Page Features.”

Table 5-8. GENERAL CATEGORY
Option	Description	Command Line
Heap size	Specify the size of the heap in bytes. Allocate a run-time heap of size bytes for use by C programs. The heap is allocated from unused data memory. If not enough memory is available, an error is reported.	`--heap size`
Min stack size	Specify the minimum size of the stack in bytes. By default, the linker allocates all unused data memory for the run-time stack. Alternatively, the programmer may allocate the stack by declaring two global symbols: `__SP_init` and `__SPLIM_init`. Use this option to ensure that at least a minimum sized stack is available. The actual stack size is reported in the link map output file. If the minimum size is not available, an error is reported.	`--stack size`
Use local stack	Check to prevent allocating the stack in extended data space memory. Uncheck to allow allocating the stack in extended data space memory.	`--local-stack` `--no-local-stack`
Allow overlapped sections	Check to not check section addresses for overlaps. Uncheck to check for overlaps.	`--check-sections` `--no-check-sections`
Init data sections	Check to support initialized data. Uncheck to not support.	`--data-init` `--no-data-init`
Pack data template	Check to pack initial data values. Uncheck to not pack.	-`-pack-data` `--no-pack-data`
Create handles	Check to support far code pointers. Uncheck to not support.	`--handles` `--no-handles`
Create default ISR	Check to create an interrupt function for unused vectors. Uncheck to not create a default ISR.	`--isr` `--no-isr`
Remove unused sections	Check to not enable garbage collection of unused input sections (on some targets). Uncheck to enable garbage collection.	`--no-gc-sections` `--gc-sections`
Fill value for upper byte of data	Enter a fill value for upper byte of data. Use this value as the upper byte (bits 16-23) when encoding data into program memory. This option affects the encoding of sections created with the `psv` or `eedata` attribute, as well as the data initialization template if the `--no-pack-data` option is enabled.	`--fill-upper=value`
Stack guardband size	Enter a stack guardband size to ensure that enough stack space is available to process a stack overflow exception.	`--stackguard=size`
Additional driver options	Type here any additional driver options not existing in this GUI otherwise. The string you introduce here will be emitted as is in the driver invocation command.
Use response file to link	Check to create a makefile that uses a response file for the link step. In Windows® OS, you have a maximum command line length of 8191 chars. When linking long programs, the link line might go over this limit. MPLAB XC-DSC provides a response file work-around. See MPLAB X IDE documentation, Troubleshooting section, for details. Uncheck to not use a response file.

Table 5-9. Symbols and Macros Category
Option	Description	Command Line
Linker symbols	Create a global symbol in the output file containing the absolute address (`expr`). You may use this option as many times as necessary to define multiple symbols in the command line. A limited form of arithmetic is supported for the `expr` in this context: you may give a hexadecimal constant or the name of an existing symbol, or use + and - to add or subtract hexadecimal constants or symbols.	`--defsym=sym`
Define Linker macros	Add linker macros.	`-Dmacro`
Symbols	Specify symbol information in the output.
	- Keep all
	- Strip debugging info	`--strip-debug (-S)`
	- Strip all symbol info	`--strip-all (-s)`

Table 5-10. Fill Flash Memory Category
Option	Description	Command Line
Which areas to fill	Specify which area of Flash memory to fill. No Fill - None (default). Fill All Unused - Fill all unused memory. Provide Range to fill - Fill a range of memory. Enter a range under “Memory Address Range.”
How to fill it	Specify how to fill Flash memory. Provide sequence of values - Provide a sequence under the Sequence option. Constant or incrementing value - Provide either: Constant = a value,  Increment/Decrement = No Incrementing Constant = a value,  Increment/Decrement = Increment Const OR  Decrement Const,  Increment/Decrement Constant = a value
Sequence	When Provide sequence of values is selected, enter a sequence. The form is `n1, n2, ...` where `n1` uses C syntax. Example: `0x10, 25, 0x3F, 16`.	`--fill=sequence`
Constant	When Constant or incrementing value is selected, enter a constant. Specify the constant using C syntax (e.g., `0x` for hex, `0` for octal).   Example: `0x10` is the same as `020` or `16`.	`--fill=constant`
Increment/Decrement	When Constant or incrementing value is selected, you may select to increment or decrement the initial value of “Constant” on each consecutive address. No Incrementing - Do not change constant value. Increment Const - Increment the constant value by the amount specified under the option “Increment/Decrement Constant.” Decrement Const - Decrement the constant value by the amount specified under the option “Increment/Decrement Constant.”
Increment/Decrement Constant	When Increment Const or Decrement Const is selected, enter a constant increment or decrement value. Specify the constant using C syntax (e.g., `0x` for hex, `0` for octal). Example: `0x10` is the same as `020` or `16`.	`--fill=constant+=incr` `--fill=constant-=decr`
Memory Address Range	When Provide Range to fill is selected, enter the range here. Specify range as Start:End where Start and End use C syntax. Example `0x100:0x1FF` is the same as `256:511` .	`--fill=value@range`

Table 5-11. Libraries Category
Option	Description	Command Line
Libraries	Add libraries to be linked with the project files. You may add more than one.	`--library=name`
Library directory	Add a library directory to the library search path. You may add more than one.	`--library-path=“name”`
Force linking of objects that might not be compatible	Check to force linking of objects that might not be compatible. The linker will compare the project device to information contained in the objects combined during the link. If a possible conflict is detected, an error (in the case of a possible instruction set incompatibility) or a warning (in the case of possible register incompatibility) will be reported. Specify this option to override such errors or warnings. Uncheck to not force linking.	`--force-link` `--no-force-link`
Don’t merge I/O library functions	Check to not merge I/O library functions. Do not attempt to conserve memory by merging I/O library function calls. In some instances the use of this option will increase memory usage. Uncheck to merge I/O library functions to conserve memory.	`--no-smart-io` `--smart-io`
Exclude standard libraries	Check to not use the standard system startup files or libraries when linking. Only use library directories specified on the command line. Uncheck to use the standard system startup files and libraries.	`--nostdlib`

Table 5-12. Diagnostics Category
Option	Description	Command Line
Generate map file	Create a map file.	`-Map=“file”`
Display memory usage	Check to print memory usage report. Uncheck to not print a report.	`--report-mem`
Generate cross-reference file	Check to create a cross-reference table. Uncheck to not create this table.	`--cref`
Warn on section realignment	Check to warn if start of section changes due to alignment. Uncheck to not warn.	`--warn-section-align`
Trace Symbols	Add/remove trace symbols.	`--trace-symbol=symbol`

Table 5-13. Code Guard Category - dsPIC33C/E/F and dsPIC30F Devices Only [DD]
Option	Description	Command Line
Boot RAM	Specify the boot RAM segment: none, small, medium or large.	`--boot=option_ram`
Boot Flash	Specify the boot Flash segment: none, small, medium, or large standard or none, small, medium, or large high.	`--boot=option_flash_std` `--boot=option_flash_high`
Boot EEPROM	Specify the boot EEPROM segment.	`--boot=eeprom`
Boot write-protect	Specify the boot write protected segment.	`--boot=write_protect`
Secure RAM	Specify the secure RAM segment: none, small, medium or large.	`--secure=option_ram`
Secure Flash	Specify the secure Flash segment: none, small, medium, or large standard or none, small, medium, or large high.	`--secure=option_flash_std` `--secure=option_flash_high`
Secure EEPROM	Specify the secure EEPROM segment.	`--secure=eeprom`
Secure write-protect	Specify the secure write protected segment.	`--secure=write_protect`
General write-protect	Specify the general write protected segment.	`--general=write_protect`
General code-protect	Specify the secure code protected segment: standard or high.	`--general=code_protect_std` `--general=code_protect_high`
For more information on CodeGuard™ options, see “Options that Specify CodeGuard Security Features” in the “MPLAB® XC-DSC Assembler, Linker and Utilities User’s Guide” (DS-50003590). Note: Not all development tools support CodeGuard programming. See tool documentation for more information.