FPC HowToDo: what changed
Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.
Title: FPC HowToDo
| Old | New | Line | |
|---|---|---|---|
| 1 | + | This page provides blueprints of features, both mandatory and optional, which have been implemented/tested on at least one platform, but that still have to or could be added for other platforms. When adding a new entry, please add as much technical information as needed about the existing implementations for other platforms and the generic support routines which are available. Do not just add bug fix requests, that is what [the bugtracker](https://gitlab.com/freepascal.org/fpc/source/-/issues/) is for. | |
| 2 | + | ||
| 3 | + | Note that description of [[System unit structure]] (especially the internal platform-specific implementation) provides another useful source of information for porting to new platforms (and aligning behaviour for the existing ports). In general, descriptions appearing here and related to System unit are expected to move to [[System unit structure]] sooner or later. | |
| 4 | + | ||
| 5 | + | # Mandatory | |
| 6 | + | ||
| 7 | + | ## Widestring manager | |
| 8 | + | ||
| 9 | + | - **Required for**: proper functioning of locale-dependent widestring and ansistring operations (assignments, comparisons) | |
| 10 | + | - **Platforms implemented**: Windows, unix, OS/2, generic (fpWidestring) | |
| 11 | + | - **Platforms Todo**: symbian, macos9, morphos, netware | |
| 12 | + | - **Generic usable routines**: rtl/inc/wstringh.inc, rtl/inc/wustring.inc | |
| 13 | + | - **What**: implement widestring manager helpers. Add them to your system unit if they can be linked into any binary, or into a unit called "cwstring" if they depend on an external library on which programs should not depend by default. If added to the system unit, also define *FPC_NOGENERICANSIROUTINES* at the top of your platform's sysutils unit. | |
| 14 | + | - **Existing implementations**: win{32,64,ce}/system.pp (complete? -- search for *widestringmanager*), rtl/unix/cwstring.pp | |
| 15 | + | - **Tests**: tests/test/twide*.pp, tests/test/units/sysutils/tastrcmp.pp, and some in tests/tbs and tests/webtbs. Mostly not available and still need to be written. | |
| 16 | + | ||
| 17 | + | ## i386/arm fpu/sse initialisation | |
| 18 | + | ||
| 19 | + | - **Required for**: initialising global variables indicating the presence of certain fpu types, so that the fpu exception masking routines also adjust the exception masks of these fpus. | |
| 20 | + | - **Platforms implemented**: win32 (i386), Linux (i386 and arm), FreeBSD (i386), Darwin (i386) | |
| 21 | + | - **Platforms Todo**: wince (arm), OS/2 (i386), BeOS (i386) | |
| 22 | + | - **Generic usable routines**: rtl/i386/i386.inc (*fpc_cpucodeinit*), rtl/arm/arm.inc (*fpc_cpucodeinit*) | |
| 23 | + | - **What**: call *fpc_cpucodeinit* in your system unit's initialisation code, and catch the potential "illegal instruction" exception in your exception/signal handler, checking/setting a global variable in the process indicating lacking support for the tested fpu type | |
| 24 | + | - **Existing implementations**: rtl/win32/system.pp (search for *os_supports_sse* and *fpc_cpucodeinit*), rtl/linux/system.pp and rtl/linux/arm/sighnd.inc and rtl/linux/i386/sighnd.inc (idem), rtl/bsd/system.pp and rtl/freebsd/i386/sighnd.inc (idem) | |
| 25 | + | - **Tests**: tests/test/units/math/tmask*.pp compiled with -Cfsse2 (i386) or with -Cf{fpa,fpa10,fpa11} (arm) | |
| 26 | + | ||
| 27 | + | ## Dynamic library initialization/finalization | |
| 28 | + | ||
| 29 | + | - **Required for**: Working initialization/finalization sections in dynamic libraries | |
| 30 | + | - **Platforms implemented**: windows all, Darwin, Linux | |
| 31 | + | - **Platforms Todo**: All other platforms which support dynamic libraries | |
| 32 | + | - **Generic usable routines**: compiler/ncgutil.pas (*gen_proc_symbol_end*) | |
| 33 | + | - **What**: When *current_module.islibrary* is true, | |
| 34 | + | - call the procedure whose *procdef.potype_proginit=potype_proginit* when the library is initialised | |
| 35 | + | - when *(current_module.flags and uf_finalize)\<\>0* call the *current_procinfo.procdef* when the library is finalised | |
| 36 | + | - **Existing implementations**: The darwin implementation can be found in compiler/rtl/ncgutil.pas (*gen_proc_symbol_end*). | |
| 37 | + | - **Tests**: tests/webtbs/tw7838*.pp, tests/webtbs/tw9089*.pp | |
| 38 | + | ||
| 39 | + | ## Weak linking | |
| 40 | + | ||
| 41 | + | - **Required for**: supporting weakly linking symbols (symbols which may not be available at run time, and which map to NIL in that case) | |
| 42 | + | - **Platforms implemented**: Darwin, Linux (with external assembler), Solaris | |
| 43 | + | - **Platforms Todo**: All other platforms that support dynamic libraries, and the internal assembler/linker | |
| 44 | + | - **Generic usable routines**: `svn diff -c 12009 compiler/aggas.pas` (all the rest are generic changes required for all platforms) | |
| 45 | + | - **What**: when an asmsymbol's "bind" field equals AB_WEAK_EXTERNAL, mark it as a "weak" symbol in the assembler or object file, and add the newly supported platforms to the `system_weak_linking` set in compiler/systems.pas | |
| 46 | + | - **Tests**: tests/test/tweaklib1.pp and tests/test/tweaklib2.pp (tweaklib3.pp and tweaklib4.pp are probably only necessary for Darwin, see the comments in tweaklib1.pp for more info) | |
| 47 | + | ||
| 48 | + | # Optional | |
| 49 | + | ||
| 50 | + | ## Compiler optimizations | |
| 51 | + | ||
| 52 | + | ### (u)int32x(u)int32 to (u)int64 multiplication | |
| 53 | + | ||
| 54 | + | - **Required for**: optimizing 32x32-\>64 bit multiplications (several 32 bit architectures can do this without needing to perform a full 64 bit multiplication) | |
| 55 | + | - **Platforms implemented**: PowerPC 32 and i386 | |
| 56 | + | - **Platforms Todo**: all other 32 bit architectures | |
| 57 | + | - **Generic routines**: compiler/nadd.pas (*use_generic_mul32to64*/*first_add64bitint*/*try_make_mul32to64*) | |
| 58 | + | - **What**: override *taddnode.use_generic_mul32to64* and let it return false, then add support to your architecture's muln handler for performing signed and unsigned 32 bit int to signed/unsigned 64 bit int multiplications (i.e., left.resultdef and right.resultdef = 32 bit ints, self.resultdef = 64 bit int) | |
| 59 | + | - **Existing implementations**: compiler/powerpc/ncpuadd.pas (*second_add64bit*, search for *MULHW*/*MULHWU*) | |
| 60 | + | - **Tests**: tests/test/cg/tmul3264.pp | |
| 61 | + | - **Notes**: does not occur much in at least the rtl/compiler code base | |
| 62 | + | ||
| 63 | + | ### Bit(field) getting/setting primitives | |
| 64 | + | ||
| 65 | + | - **Required for**: being able to use the generic tcginnode code and still getting (close to) optimal code, faster record register variables and faster bitpacked records/arrays | |
| 66 | + | - **Platforms implemented**: PowerPC 32/64 | |
| 67 | + | - **Platforms Todo**: all other architectures | |
| 68 | + | - **Generic routines**: compiler/cgobj.pas (*a*subsetreg*, *a*subsetref*, *a_bit_test**) | |
| 69 | + | - **What**: override (some of) the subsetreg/subsetref routines to use architecture-specific opcodes for setting/getting bits and/or bitfields (the *a_bit_test** routines mostly use the subsetref/reg routines under the hood, except for *a_bit_test_reg_reg_reg*, so in general it's better to implement special cases for the subsetreg/ref routines as these are used in more cases) | |
| 70 | + | - **Existing implementations**: compiler/ppcgen/cgppc.pas (*a_load_subsetref_regs_noindex*), compiler/powerpc/cgcpu.pas (*a_load_subsetreg_reg*, *a_load_subsetreg_subsetreg*, *a_load_regconst_subsetreg_intern*), compiler/powerpc64/cgcpu.pas (*a_load_subsetreg_reg*, *a_load_const_subsetreg*, *a_load_regconst_subsetreg_intern*) | |
| 71 | + | - **Tests**: tests/test/tparray*.pp, tests/test/tprec*.pp, tests/test/trecreg*.pp | |
| 72 | + | ||
| 73 | + | --- | |
| 74 | + | *From the Free Pascal wiki, page "FPC HowToDo", as it stood on 2023-11-05 after a change by Bart, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* | |
| 75 | + | Category: FPC Todo |