[[Assembler components in IOMD]] h2. Getting started Many peripheral modules are written in assembler, and you may wish to convert one to C. Below are some pointers to help you do so. h3. OSLib vs. _swix Of the existing C components in the system, some use swix, and some use OSLib. A discussion of the differences can be found "here":https://gitlab.riscosopen.org/RiscOS/Sources/Desktop/ShellCLI/-/merge_requests/2#note_2817. h3. GCC When starting out, for a softloadable module, it is feasible to create your first version using GCC if this is what you are familiar with, changing to use the DDE later. Note however that if using OSLib, the version in the OS source is currently different to the latest release, so some minor tweaks may have to be made; this could be avoided by setting things up to using OSLib from the OS source tree from the start. h3. cmhg When you create the cmhg file for your module, call it <code>YourModuleHdr</code>, so that later on when you integrate your source into the OS, the makefile will do some things for you automatically. If you are writing a module task, and wish to use no wimpslot, you'll need to use a bc. library-enter-code: ... line, so that you can setup/destroy a stack before/after entering the C code (for an example of how to do this, look at "AcornURI":https://gitlab.riscosopen.org/RiscOS/Sources/Networking/URI). This syntax is not available in cmunge, but you can do this with the GNU tools as bc. objcopy --redefine-sym _clib_entermodule=_my_entermodule YourModuleHdr.o In some situations you'll need to create custom veneers over and above those provided by cmhg; to understand these, look [[Using C in assembler components|here]]. Note that you might be able to avoid work by shuffling registers around in assembler and then calling one of the usual cmhg veneers. h3. Reset Many modules contain a handler for the service call Service_Reset (&27 - a.k.a. Service_PostReset). You do not need to write any code for this, as the OS no longer uses this call. h3. Tips and Tricks As the system is uninterruptable in supervisor mode (SVC32), it is good to prototype ideas as a user-mode application. You can then also use tools such as DDT. Your module will likely include one or more pieces of "pure" logic; remember that you may develop these on any system you like, and that keeping them well separated from the rest of the module code will help anybody investigating your work in the future. Fortify (which you will need to find yourself) can be used during development for debugging memory allocation problems, overruns etc. Write tests as you go along, or even before you start. This helps to avoid embarrassment for you, and to again make maintenance easier. h3. Further help When you run into problems, make a post in the "Community Support forum":https://www.riscosopen.org/forum/forums/11. If you're unsure about an approach you're taking, or need someone to look over your work, drop by the "Code Review forum":https://www.riscosopen.org/forum/forums/3. We will also be happy to give advice in the forums on which modules are suitable for looking at as a starter. People have taken different approaches to this task: you can read about some of them "here":https://www.riscosopen.org/forum/forums/5/topics/731 and "here":https://www.riscosopen.org/forum/forums/5/topics/15990#posts-112599. h2. Build system Now you've got a working module, and a copy of the DDE, what next? <code>$</code> here means the root directory of the component you are working on (e.g. if you are converting the window manager, then this is <code>RiscOS.Sources.Desktop.Wimp</code>). h3. RiscOS.Sources.BuildSys.ModuleDB Change from "ASM" to "C". This is required to successfully build as ROM (since an extra linking step must be performed), and to cause the CI script to be created automatically. h3. Component Remove <code>$.rm./gitignore</code> if present and update <code>$./gitignore</code> to ignore bc. /aof/ /h/YourModuleHdr /linked/ /Makefile.d /o/ /objs/ /od/ /rm/ h4. Add $./gitlab-ci/yml with lines bc. include: - project: 'Support/CI' file: '/YourModule.yml' Note that CI will only happen once your change to ModuleDB has been merged. The results appear on your fork of the component. h4. $./gitattributes Add lines bc. c/** gitlab-language=c linguist-language=c linguist-detectable=true h/** gitlab-language=c linguist-language=c linguist-detectable=true cmhg/** gitlab-language=cmhg linguist-language=cmhg linguist-detectable=true h4. $.cmhg.YourModuleHdr If you used objcopy as mentioned above, now is the time to add a bc. library-enter-code: ... line instead. h5. Useful includes bc. #include "VersionNum" then your help string can be bc. help-string: YourModule Module_MajorVersion_CMHG Module_MinorVersion_CMHG Bring in bc. #include "Global/Services.h" for service call numbers and bc. #include "Global/SWIs.h" for your SWI chunk base. h4. $.s.YourModule Remove any old assembler source. h4. $.Makefile The makefile will look something like this bc.. # Makefile for YourModule COMPONENT = YourModule CMHGDEPENDS = module INCLUDE_OSLIB ?= -IOS: CINCLUDES = ${INCLUDE_OSLIB} LIBS = ${OSLIB} ${ASMUTILS} OBJS = module swis HDRS = ASMHDRS = YourModule include CModule # Dynamic dependencies: p. CMHGDEPENDS is a list of objects that reference anything from the cmhg header <code>h.YourModuleHdr</code>. Obviously if you aren't using a library, don't include it. AsmUtils provides the base address of the module. Fill out OBJS with all the object files. h3. License Every source file you create must have a license summary as a comment at the start. Most of the OS source is licensed under Apache 2.0, so you could use the following for your C source: bc. /* Copyright <Year> <Your name or organisation> * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ h3. Submitting Follow the "git cheatsheet":https://www.riscosopen.org/content/documents/git-cheatsheet. h3. CI on GitLab Having done the CI setup above, once you push your work to your fork on GitLab, the CI will run automatically. You can see the result by clicking on "CI/CD" on the left hand pane when viewing your repository (N.B. your fork). Click on the icons in the "Status" column. Each time you push you will get two pipelines that run. N.B. Currently none of the "rom_" jobs will pass, and neither will "softload_gnu". Once "softload" passes there will be available in the far right-hand column of the pipelines screen an option for anybody to download the softload module.