What's the meaning of W suffix for thumb-2 instruction?

Question

There is a w suffix for thumb-2 instruction as below, how does it change the semantic of the instruction without it? The search result is very noisy and I didn't get the answer.

addw r0, r1, #0

Answer 1

I see ADDW in Cortex-M3 TRM Table 2-5

Data operations with large immediate
ADDW and SUBW have a 12-bit immediate. This means they can replace many from memory literal loads.

It is also mentioned in Quick Reference

add wide T2 ADD Rd, Rn, #<imm12>

Looks like the assembler would recognize the immediate constant <= 12 bits, and do the needful.

In the context where you see it, it is an ordinary "add".

Answer 2

Simply enough, W means "wide". It is the 32-bit version of the instruction, whereas most Thumb instructions are 16 bits wide. The wide instructions often have bigger immediates or can address more registers.

Edit: Some of the comments seem confused about the difference between addw and add.w. The only essential difference is how the immediate is encoded.

add.w:  imm32 = ThumbExpandImm(i:imm3:imm8);
addw:   imm32 = ZeroExtend(i:imm3:imm8, 32);

Answer 3

Different encodings of an instruction should have distinguishing syntaxes so when you disassemble a binary you should notice which encoding was used. This also helps when you assemble back a disassembled binary, resulting binary should be the one you start with.

In your case using addw instead of add doesn't change the semantic of instruction as it is an add operation. However it certainly forces assembler to produce Encoding T4 (32-bit) of add instruction, as that's dictated by the specification.

Summary when assembling you can use just add mnemonic and assembler would choose the right encoding and you can see that in the object dump.

int f1(int i) {
    asm volatile("add r0, #0");
    asm volatile("add r0, #257");
}

00000000 <f1>:
   0:   f100 0000   add.w   r0, r0, #0
   4:   f200 1001   addw    r0, r0, #257    ; 0x101
   8:   4770        bx  lr
   a:   bf00        nop