1 Introduction

The C compiler supports two CDM-16 target triples. They differ in the programs used for assembling and linking.

Short target triple	Full target triple	Assembler	Linker	Assembly syntax	Object format
cdm	cdm-unknown-unknown-unknown	Built-in LLVM assembler	LLVM LLD	GNU/AT&T	ELF (32-bit)
cdm-cocas	cdm-unknown-unknown-cocas	Cocas	Cocas	Cocas syntax	Cocas text-based format

The default target triple is cdm-cocas.

[!NOTE] The two targets use incompatible assembly and object formats. This means that assembly code and libraries made for different targets cannot be used in the same project. An object file conversion tool is planned, but has not been implemented yet.

2 ELF-based target

Usage:

clang-cdm --target=cdm # ...

The cdm target (also referred to as "the ELF target") is more feature-rich than cdm-cocas, but is not compatible with existing Cocas code. It is recommended for new projects.

2.1 Linker output format

By default, the C compiler produces an ELF object file as its final output. An ELF file needs to be converted to a hex text-based format before it can be used as a RAM/ROM image in Logisim. This can be done with the llvm-objcopy-cdm tool included in the toolchain.

Use the -O logisim option to produce a Logisim memory image:

llvm-objcopy-cdm -O logisim LINKER_OUTPUT.elf MEMORY_IMAGE.img

Alternatively, use -O binary to produce a raw binary image:

llvm-objcopy-cdm -O binary LINKER_OUTPUT.elf MEMORY_IMAGE.bin

2.2 Section placement

Unlike Cocas, LLVM LLD does not support absolute sections (asect directives). In fact, there is no distinction between "absolute" and "relocatable" sections. Section placement is controlled by linker scripts.

The target provides a few default linker scripts used in the absence of the -T option. These scripts place the interrupt vector table (IVT) at the start of the address space, followed by code and data sections.

The default linker scripts are designed to be used together with crt0.o. If you decide to replace one, you will likely need to replace the other. For more information, see Default linker scripts and Standard library.

2.3 Assembly

Assembly code can be compiled directly with Clang or with the dedicated llvm-mc-cdm tool.

As stated in the introduction, this target uses GNU assembly syntax, which is different from the syntax used in Cocas. Regular instructions are identical, but assembler directives are completely different. Here is a comparison of some common directives.

Description	Cocas	GNU
Local symbol	symbol:	symbol:
Global symbol	symbol>	.global symbol symbol:
Extern symbol	symbol: ext	not used, undefined labels are extern by default
Switch section	rsect text	.section .text
End of file	end	not used
String constant	dc "string"	.ascii "string"
Word constant	dw 0xF00D	.short 0xF00D
Byte constant	db 0xAF	.byte 0xAF
Align to multiple	align 8	.align 8

See the GNU docs for a full list of supported directives.

There is an important difference in label visibility semantics. In Cocas, a private label is only visible within the same section it was defined in. In a GNU-compatible assembler, a private label is visible in the entire file. See Local Symbol Names in GNU docs for alternatives to section-local labels.

Another difference lies in section handling. In ELF, section names are standardized. Depending on the type of the section, its name should be .text, .data, .rodata, or .bss. If you want to use a custom name for a section, you'll need to specify its attributes and use a custom linker script. See the GNU docs for .section (the variant for ELF targets).

3 Cocas-based target

Usage:

clang-cdm --target=cdm-cocas # ...

The cdm-cocas target is intended for drop-in usage in existing Cocas-based projects. It is quite limited compared to the cdm target.

3.1 Cocas location

The compilation driver needs to locate Cocas to use it when generating an object file (with -c) or linking an executable (without -c or -S).

It looks in the following places (in this order):

• The value of the COCAS environment variable;
• cocas in the toolchain binary directory;
• cocas in the PATH environment variable;
• cocas in the current working directory.

The install script downloads and sets up a stable version of cocas automatically.

3.2 Limitations

Here are some notable limitations of the cdm-cocas target:

• File-local symbols are not supported (a section cannot reference a label defined inside another section without making it global);
• Weak symbols and imports are not supported;
• Assembly label aliases are not supported;
• Each object file generated by the compiler is a single relocatable section;
• Harvard memory model is not supported.