Home

OS-9 Porting Guide

image

Contents

1. codes Parameters direction is the direction value provided from the notification services the NTFY_DIR_TOROM value indicates a transition into the ROM from the operating system the NIFY_DIR_TOSYS values indicates a transition to the operating system from the ROM cdev points to the console device structure for the device Starting up the Low Level Serial I O Module During the early stages of system bootup the bootstrap code searches for and initializes all low level system modules included in the boot image The initialization entry point for the low level system modules is supplied in a relocatable r file This entry point branches to the C function p2start which you need to provide for each of your low level I O modules The initialization routine performs these tasks Allocates initializes the console device record for the device Makes the entry points for its services available through the consdev record Initializes configuration data for the I O device Installs its consdev record on the list of I O devices in the console services record An example p2start routine for a low level I O module follows The console device record is allocated in the module s static data area consdev cons r allocate console device record error_code p2start Rominfo rinf bootstrap services record structure pointer u_char glbls bootstrap global data pointer Cons_svcs conso
2. Configuration Elements Description Type Size NTFY_REVS Structure version u_int16 NTFY_MAX_NOTIFIERS Maximum number of u_int32 registered notifiers For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about this function OS 9 Porting Guide Console I O Module Services The console module provides a high level I O interface to the entry points of the low level serial device driver configured as the system console These services are made available through the console services field of the rominfo structure Assuming the variable rinf points to the rominfo structure rinf gt cons can be used to reference the console services record The header file MWOS SRC DEFS ROM rom h contains the structure definitions for the rominfo structure and the console services record cons_SVCS The console services are required when any of the following conditions are met 1 Console dialog is required to boot the system for example using a boot menu or menus 2 Local system state debugging with RomBug is required 3 The communications port is required to support downloading or remote debugging If none of these are required in the final system the console module the corresponding low level serial modules and the console and communications port configuration modules can be omitted The following services are available through the console serv
3. Module Syntax error_code l1l_install char xname u_int8 portaddr u_int8 selfid u_int8 reset Bootdev bdev Rominfo rinf Description 11_install1 installs the low level SCSI host adapter module The port address selfidand reset values are placed into the appropriate 11scsi_svcs record and the host adapter s 11_init routine is called Parameters name points to the name of the host adapter module portaddr is the address of the SCSI port selfid is the host adapter s SCSI identification reset is a flag to indicate if the host adapter should reset the SCSI bus or not bdev points to the booter s bootdev record rinf points to the rominfo structure readsccs WX microware Reads a Direct Access Device Syntax u_int32 readsccs u_int32 u_int32 u_char Bootdev Rominfo Description numsects blkaddr Hutt bdev rinf readsccs reads data from a direct access device Parameters numsects blkaddr buff bdev rinf is the number of blocks to transfer is the direct access device block address points to the data buffer points to the booter s bootdev record points to the rominfo structure rewind_tape Rewinds a Sequential Device Syntax error_code rewind_tape Bootdev bdev Rominfo rank 3 Description rewind_tape positions a sequential device to the beginning of information Parameters bdev points to the booter s bootdev record
4. Virtual Console PPC CMDS BOOTOBJS ROM iovcons CMDS BOOTOBJS ROM conscnfg The conscnfg module looks to the console record in the cnfgdata module to determine which low level driver should be installed as the system console driver To configure iovcons as your system console declare VirtualConsole as the name of your console device in the console port declarations section of config des Figure 10 1 lt MWOS gt 0S9000 scllio and iovcons Directories and Files OS9000 BOOTS EXAMPLES optional aema VCONSLIP PORTBOOT bootfile ml readme txt The console device record name is specified in the config des or default des where applicable file in the CNFGDATA directory All other fields of the console record are ignored by iovcons The following excerpt from config des provides an example of how to declare a macro default des where applicable CNFGDATA config des makefile TESTBOOT optional Console port define CONS NAME VirtualConsole 1 0 Using Hardware Independent Drivers WX MICROWARE 206 OS 9 Porting Guide Chapter 11 Creating a Ticker This chapter includes the following topics Guidelines for Selecting a Tick Interrupt Device OS 9 Tick Time Setup Tick Timer Activation Debugging the Ticker WX MICROWARE 207 KX MICROWARE Guidelines for Selecting a Tick Interrupt Device Th
5. interrupt service routine entries Table 9 1 SCF Device Driver Static Storage Name Description v_init v_read v_write This field contains the address of the driver s initialization routine The initialization routine is responsible for performing the actual initialization of the device hardware SCF calls this routine when an I_ATTACH service request is made This field contains the address of the driver s read routine The driver s read routine is only called if the driver s input operates in polled mode For more information refer to the v_pollin field of the logical unit static storage structure definition Table 9 4 on page 160 This field contains the address of the driver s write routine The driver s write routine is only called if the driver s output operates in polled mode For more information refer to the v_pollout field of the logical unit static storage structure definition Table 9 4 on page 160 KX MICROWARE Table 9 1 SCF Device Driver Static Storage continued Name Description v_getstat This field contains the address of the driver s get status routine The driver s get status routine is only called for get stat service requests that are defined to call the driver and unknown getstat function codes v_setstat This field contains the address of the driver s set status routine The driver s set status routine is only called for set stat service reque
6. For More Information Refer to OS 9 for the lt target gt Board Guide or Getting Started with OS 9 for lt target gt for other examples of how hardware can be set up Install Microware software distribution on host system Follow the installation instructions included with your Microware software distribution media The distribution media contain all of the files that make up the e OS 9 boot code e Operating system e Related utilities Some files are source code text files Most of the other files are makefiles and object code files The files are organized into subdirectories according to major subsystems ROM IO CMDS for example in a master directory known as the MWOS structure During the installation process the file system is copied into the MWOS directory structure You need to use a hard disk based system with sufficient storage capacity to contain the entire file system Microware has adopted this general directory structure across all of its product lines The files in the distribution package assume this specific file and directory organization They do not compile and link correctly if the organization is different Microware uses the file name suffixes shown in the following table to identify file types Table 1 1 Microware File Name Suffixes Suffix Definition a Assembly language source code C C language source code CC C language source code d Definitions defs source code for as
7. llvl serial comm console slip u_intl16 proto_mtu Max Xmission Unit for protocol proto_hdr_len Space requirements for header proto_tlr_len Space requirements for 8 trailer u_char proto_flags Protocol status amp type flags 80 Creating a Low Level Ethernet Driver u_char proto_rsvl u_int32 proto_addr u_char proto_globs u_int32 proto_vector proto_priority void proto_port_addr fields added at V2 WX MICROWARE align on longword boundary vl only IP address null except drivers Pointer to protocol srvr globals vector for lldrivers Irisi priority lldriver port address Extended IP address Physical MAC address IRQ level for low level u_char proto_ipaddr 16 u_char proto_hwaddr 16 u_int32 proto_irgqlevel char proto_drv_name u_int32 proto_rsv2 6 else int reserved endif i values for proto_flags define PVR_RELIABLE define PVR_LLISR_REG_REQ define PVR_LLISR_REG_ERR The following flag is to be used to indicate which driver to use drivers fdriver reserved for emergency expansion name identifier of protocol 0x01 reliable protocol 0x02 request LLISR registration 0x04 the LLISR reg req failed if the interface IP address does not match that specified during the
8. process to signal on SS_SENDSIG request signal code associated system path v_dedoff 3 process to signal on SS_DCOFF request v_dcdon 3 signal code signal code associated system path to signal on SS_DCON request associated system path process Scf_lu_stat v_outdev output device s static storage pointer u_int32 v_pdbufsize SCF s path buffer size for this device v_maxbuff input buffer maximum high water mark u_int32 v_insize size of input buffer v_incount number of bytes in input buffer u_char v_inbufad input buffer address y_infill input buffer next in pointer yv_inempty input buffer next out pointer yv_inend input buffer end of buffer pointer u_int32 v_outsize size of output buffer v_outcount number of bytes in output buffer u_char v_outbufad output buffer address yv_outfill output buffer next in pointer XX micRoware v_outempty output buffer next out pointer v_outend output buffer end of buffer pointer lock_id v_lockid I O lock identifier u_int 32 v_use_cnt logical unit user count u_int 32 v_resrvd 5 reserved space Scf_path_opts v_pdopt ptr to path descriptor options section scf_lu_opts v_opt logical unit options section ifdef DEV_SPECIFICS DEV_SPECIFICS driver specific static variables endif scf_lu_stat
9. Convert an integer to ASCII outhex Display one hexidecimal digit out Lhex Display a hexidecimal byte out 2hex Display a hexidecimal word out 4hex Display a hexidecimal longword rom_udiv Unsigned integer division A A The Core ROM Services KX MICROWARE Table A 3 p2lib 1 Functions continued Function Description setexcpt Install exception handler swap_globals Exchange current globals pointer For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions 326 OS 9 Porting Guide Th r DNA Cani The Core ROM Services getrinf Get the Rominfo Structure Pointer Syntax error_code getrinf Rominfo rinf_p Description getrinf finds and returns the pointer to the rominfo structure from the system globals Parameters rinf_p is the address where get rinf stores the pointer to the rominfo structure fal Note The current globals register needs to be set to point at the system globals when the service is invoked OS 9 Porting Guide 327 WX microware hwprobe Check a System Hardware Address Syntax error_code hwprobe void addr u_int32 ptype Rominfo rinf Description hwprobe sets up the appropriate handlers to catch machine check exceptions and probes the system memory at the specified address attempting to read either a byte word or long In
10. FD Free List Lock Descriptor Lock descriptor structure for locking the FD free list WX micRoware Table 13 6 RBF Drive Information Structure continued Name Description v_fd_free_list v_blks_rsrc_lk v_blks_list v_reserved List of Free FD Block Structures This field points to the list of free file descriptor block structures Free Block List Lock Descriptor Lock descriptor structure for locking the free block list List of Free Block Buffers This field points to the list of free block buffers used for buffering data blocks Reserved for Future Enhancements Disk Device Options This section describes the definitions of the device options for RBF type devices The structure definition of the device options is shown here This structure is defined in the header file rof n IOMAN copies the device options from the device descriptor module into the logical unit static storage when the device is attached typedef struct rbf_lu_opts u_char lu_stp lu_tfm lu_lun lu_ctririd u_int32 lu_totcyls u_int32 lu_reserved 4 rbf_lu_opts Rbf_lu_opts step rate DMA transfer mode drive logical unit number controller ID total number of cylinders reserved for future expansion Table 13 7 RBF Disk Device Option Structure Name Description lu_stp Step Rate Floppy disks This location contains a code that sets the head stepping rate used with the driv
11. Table 9 4 SCF Logical Unit Static Storage Fields Name Description v_vector Interrupt Vector This field contains the associated interrupt vector number for the device Note The OS 9 Configuration Reference uses hardware_vector v_irglevel Interrupt Level This field contains the interrupt level of the device v_priority Interrupt Priority This field contains the polling priority of the device v_pollin Polled Input Flag This field indicates whether the device s input operates in interrupt or polled mode If the driver uses polled mode SCF calls the driver s READ routine for every character A non zero value indicates polled mode A zero value indicates interrupt driven input Table 9 4 SCF Logical Unit Static Storage Fields continued Name Description v_pollout v_inhalt v_hangup Polled Output Flag This field indicates whether the device s output operates in interrupt or polled mode If the driver uses polled mode SCF calls the driver s WRITE routine for every character A non zero value indicates polled mode A zero value indicates interrupt driven output Input Halted Flag This field indicates whether or not input to the device has been halted It is non zero if an X OFF character has been sent and input halted Data Carrier Lost Flag This field is non zero when the data carrier line has been lost indicating a lost connection XX micRoware Table 9 4 SCF Logical Unit
12. Total Number of Cylinders on Drive This defines the total number of physical cylinders on the drive This value is useful when working with physical drives that have been split in to a number of logical drives Only the driver uses this field define TOTCYLS 80 Table 13 10 RBF Macro Definitions continued Name Description and Example CTRLRID SCSI Controller ID This defines the SCSI controller ID for the device being accessed Only the driver uses this field You can use it for other purposes on non SCSI devices define CTRLRID 0 DRIVERNAME Name of Driver This defines the name of the RBF driver used to access the device described by the descriptor define DRIVERNAME rb5400 WX MICROWARE Device Specific Non Standard Definitions Step 1 Step 2 Step 3 Step 4 In addition to the standard fields described in rbf des you can add specific definitions for particular driver descriptor combinations It is usually done to accommodate specific RBF drivers Use these steps for adding device specific information to a descriptor Create an EditMod source file with the structure definition of the additional information For example in rosccs des struct dev_specific pointer u_int32 ds_ldrvnam ldrvnam u_int32 ds_scsiopts SCSI options string ldrvnam SCSI low level driver name Change the driver s header file to indicate the driver has device specific i
13. Validate bootfile modules Find module list entry Find beginning of module De initialize low level system modules Delete module from module list Initialize low level system modules Insert module into module list Scan for modules For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions goodmodule Validate Bootfile Modules Syntax u_int32 goodmodule u_char modptr u_int32 bootsize u_int32 modsize u_int32 kerchk Rominfo rinf Description This service validates a bootfile module optionally checking if the module is the kernel Parameters modptr is the address of the module bootsize is the size of all modules within the boot image modsize is a pointer to the returned size of the module in bytes if it is good kerchk is a flag specifying if the module should be checked as the kernel A non zero value indicates the module s name must match the kernel name for the service to succeed rinf is a pointer to the rominfo structure WX microware rom_findmle Find Module List Entry Syntax u_int32 rom_findmle u_char modptr Mod_list mleptr Rominfo rinf Description This service returns the module list entry for the specified module Parameters modptr points to the low level system module mleptr points to the returned module list entry pointer rinf points to the rominfo structure rom_fi
14. parity v_stopbits stop bits v_wordsize word size v_rtsstate RTS state disable 0 enable non zero v_dcdstate current state of DCD line v_reserved 9 reserved for future use scf_lu_opts Table 9 5 SCF Logical Unit Static Storage Options Name Description v_optsize v_class v_err v_pause v_line Options Section Size This field specifies the size of the logical unit options section Device Type DT_SCF 0 This field specifies the device type This should be zero for SCF The device types are defined in the io h header file Accumulated Errors This field is used to accumulate I O errors Typically the IRQ service routine uses it to record errors so they can be reported later when SCF calls one of the device driver routines Pause Flag This field tells SCF when there is an immediate pause request from the input device It causes SCF to suspend output from I_WRITLN until a pause character is entered from the input device Lines Before End of Page This field contains the number of lines left to output until a page pause occurs end of page XX micRoware Table 9 5 SCF Logical Unit Static Storage Options continued Name Description v_intr v_quit v_psch v_xon Keyboard Interrupt Character This field specifies the keyboard interrupt character When a keyboard interrupt character is entered a keyboard interrupt sign
15. Parameters rinf points to the rominfo record structure cdev points to the console device record for the device WX microware cons_read Read Character From I O Port Syntax u_char cons_read Rominfo rinf Consdev cdev Description cons_read returns a character from the device s input port cons_read repeatedly calls cons_check until a character is present cons_read should not echo the character The only special character handling it might perform is XON XOFF processing if the CONS_SWSHAKE flag is set in the cons_flow field of the console device structure Parameters rinf points to the rominfo record structure cdev points to the console device record for the device cons_stat Set Status on Console I O Device Syntax u_int32 cons_stat Rominfo rant Consdev cdev u_int32 code Description cons_stat changes the operational mode of the I O module Parameters rinf points to the rominfo record structure cdev points to the console device record for the device code is the low level setstat code indicating operational mode change The supported setstat codes are defined in MWOS SRC DEFS ROM rom h and described as follows CONS_SETSTAT_POLINT_OFF Indication Issued when hlproto no longer requires the services of the communications port Operation Disable receive interrupts on port CONS_SETSTAT_POLINT_ON Indication Issued when hliproto requires the services o
16. Step 6 Test the disk driver using the following procedure Note You can omit Steps 1 and 2 if the necessary system modules are in ROM After a reset set the debugger s relocation register to the RAM address where you want the system modules now including the console driver loaded Download the system modules Do not insert breakpoints yet Set the debugger s relocation register to the RAM address where you want the disk driver and descriptor loaded Ensure this address does not overlap the area where the system modules were previously loaded Download the disk driver and descriptor modules Do not insert breakpoints yet Type gb to initiate the boot process If a menu appears select the Boot from ROM option ro If all is well the following message should appear An OS 9000 kernel was found at S xxxxxxxx This is followed by a register dump and a RomBug prompt If you do not see this message the system modules were probably not downloaded correctly or were loaded into the wrong memory area Type gb again This executes the kernel s initialization code including the OS 9 module search You should get another register dump and debug prompt Step 7 Step 8 Step 9 If you want to insert breakpoints in the disk driver do so now This is greatly simplified by attaching to the driver Type gb again This should start up the system If all is well anda breakpoint was not encountered first you shoul
17. device name install the record structure on the list of available I O modules cdev gt cons_next console gt rom_conslist console gt rom_conslist cdev return SUCCESS The default value definitions used to initialize the device configuration data should be placed in the target specific syst ype h header file leaving the I O module source code portable across platforms If the same I O module is used with the console and communications ports an additional console device record for example comm_r should be allocated and initialized with the proper data for the communications port Both console device records should be added to the list of available devices Note The console and communications port configuration modules conscnfg and commcnfg using the configuration data module cnfgdata determine which console device record is selected as console and communications port Chapter 5 Creating a Low Level Ethernet Driver Low level Ethernet drivers enable communications between the target and the host Ethernet drivers support boot device and debugger operations and can provide other functionality such as console services Low level Ethernet drivers communicate to low level IP 11 ip receiving and sending data as required 11ip also communicates with the low level TCP 11tcp and low level UDP 11udp protocols forwarding datagrams up to the appropriate protocol and receiving datagrams to
18. 35 Debugger Prompt to the Kernel Entry Point 35 Kernel Entry Point to the Shell Prompt OS 9 Technical Manual 3 WX MICROWARE Chapter 2 Creating Target Port Directories 37 38 lt MWOSs gt O0S9000 Ports Directory Structure 39 Creating Target Port Directories Chapter 3 Porting the Boot Code 41 42 Porting the Bootstrap Code 43 The rom_cnfg h File 44 Bootstrap Stack Top and Boot Module Memory 45 Bootstrap Memory Lists 46 The RAM Search 47 The Special Memory Search 47 The systype h File 48 The sysinit c File 48 The sysinit Entry Point 49 The sysinit1 Routine 49 The sysinit2 Routine 49 The sysreset Routine 50 The initext Module 52 Configuring the Low Level System Modules 52 Adding Configuration Information to systype h 53 Modifying Low Level System Module makefiles 53 Modifying coreboot ml 55 Building the Boot Image Chapter 4 Creating Low Level Serial I O Modules 57 58 Creating the Low Level Serial I O Modules 59 Building the Low Level Serial I O Modules 61 The Console Device Record 62 Low Level Serial I O Module Services 75 Starting up the Low Level Serial I O Module OS 9 Technical Manual Chapter 5 Creating a Low Level Ethernet Driver 77 78 Creating a Low Level Ethernet Driver 79 Required Ethernet Driver Functions 79 81 Proto_srvr Structure The Low Level Ethernet Driver Entry Point Services 92 Additional Utility Functions 95 Low Level ARP 103 Other Functions Chapter 6 Creating a Low Level
19. 75 baud 9 1800 baud F 9600 baud 3 110 baud A 2000 baud 10 19200 baud 4 134 5 baud B 2400 baud 11 31250 baud 5 150 baud C 3600 baud 12 38400 6 300 baud v_parity Parity This field specifies the parity to be used 0 no parity 1 odd parity 2 even parity 3 mark parity 4 space parity XX micRoware Table 9 5 SCF Logical Unit Static Storage Options continued Name Description v_stopbits v_wordsize v_rtsstate v_dcdstate Stop Bits This field specifies the number of stop bits to be used 0 1 stop bit 1 1 1 2 stop bits 2 2 stop bits Bits Per Character This field specifies the number of bits per character RTS Line State This field controls the state of the RTS line Itis useful for drivers wanting to use hardware handshaking When this field is zero the RTS line is disabled When it is non zero it is enabled Current DCD Line State This field indicates the state of the DCD Line SCF Path Descriptor This section describes the definitions of the path descriptor for SCF type devices The structure definition of the path descriptor is shown here This structure is defined in scf h SCF initializes the path descriptor options section from the specified device descriptor module when a path is opened to an SCF device The path descriptor options can later be changed using the SS_PATHOPT function of the I_GETSTAT and I_SETSTAT service requests or from the keyboard u
20. A The Core ROM Services KX MICROWARE For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions 310 OS 9 Porting Guide mem_clear Clear Memory Syntax void mem_clear u_int32 size char addr Description mem_clear clears memory Memory allocated from boot memory pools is always cleared Parameters size is the size of the memory region in bytes to clear addr is the address of the memory region to clear WX microware rom free Free Allocated Memory Syntax u_int32 rom_ free u_int32 size char addr char Rominfo Description rom_free returns memory to memory pool If the request is being made after the operating system is up an_os_srtmem call is made on behalf of the caller Parameters size is the size of the memory region in bytes being returned addr is the address of the memory region being returned Rominfo is the rominfo pointer rom_malloc Allocate Memory Syntax u_int32 rom_malloc u_int32 size char xaddr Rominfo Lan 3 Description rom_malloc allocates memory from the memory pool If the request is being made after the operating system is up an_os_srqmem call is made on behalf of the caller Parameters size points to the size of the memory being requested in bytes If the size is rounded up to some block size multiple during allocation the value i
21. For example memory search list x7 _asm memlist dc 1 4000 80000 first memory segment includes ROM data area and stack dc 1 400000 1000000 second memory segment desl Q dce 1 fff40000 S f L F80000 ROM search area dc l1 0 0 0 0 0 extra fields for patching lists at WX MICROWARE In this example the bootstrap code 1 Uses RAM from the beginning of the first memory segment for its data area and stack The PowerPC vectors are initialized at 0 4000 2 Searches for RAM memory following its stack to 80000 3 Searches for RAM memory in the range 400000 to 1000000 The next zero word terminates the RAM search list The ROM search list follows the RAM search list In this example the ROM search list causes the bootstrap code to search for ROM memory between FFF40000 and FFF80000 These memory lists are used by the boot c source file when it builds a table of available memory Each list is searched for valid memory segments and each valid segment is added to the memory table The RAM Search The first part of the search list defines the areas of the address space where the bootstrap code should normally search for RAM memory This reduces the time it takes for the system to perform the search It also prevents the search and also OS 9 from accessing special use or reserved memory areas such as O controller addresses or graphics display RAM The first entry or bank in this list must point
22. IOMAN also allocates a logical unit static storage area for each drive on acontroller The size of this storage area is specified by the device descriptor module m_data The structure of logical unit static storage is described earlier in this chapter The format of the part of driver static storage required by RBF is shown here and defined in the header file rof h This is the dispatch table pointed to by the v_dr_stat field of the device list described in the previous chapter typedef struct rbf_drv_stat u_int32 funcs number of functions ov init address of driver init routine LA v_read address of driver read routine v_write address of driver write routine v_getstat address of driver getstat routine v_setstat address of driver setstat routine v_term address of device terminate routine lock_id v_drvr_rsrc_id the driver s resource lock ID process_id v_busy process using the device v_wake for use by the driver rbf_drv_stat Rbf_drv_stat RBF Device Driver Subroutines As with all device drivers RBF device drivers use a standard executable memory module format with a module type of MT_DEVDRVR Within the driver s global static storage resides the dispatch table to the driver functions Each function should return 0 if the operation was successful Otherwise it should return an appropriate error code Followi
23. KX MICROWARE Alternatives for Creating a Console I O Driver You must have an OS 9 driver module for your console device There are three options for creating a console I O driver and descriptor 1 For the initial port to a board you can use scllio instead of creating a high level SCF driver See Chapter 10 Using Hardware Independent Drivers for more information on using this hardware independent high level driver during the initial port to a board If you use this option you can copy the SCF SCLLIO DESC from one of the example port directories into the lt Target gt port directory you created This serves as your console driver for the initial board port and you can use the remainder of this chapter later when you want to create a high level SCF driver If you want to use a high level SCF driver for your console I O driver you can use the procedures in the Creating an SCF Driver Descriptor section to find and use a Microware supplied serial driver example If you want to use a high level SCF driver for your console I O driver but Microware did not provide one matching the serial device driver chip on your board you can use the Creating an SCF Driver Descriptor section and the referenced material in this chapter to create a driver and build a descriptor Creating an SCF Driver Descriptor Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 This section summarizes the steps re
24. base track Sector Base Offset This is the offset to the first accessible sector number Sector 0 is not always the base sector Number of Tries This is the number of times a device tries to access a disk before returning an error Logical Block Size This is the logical block size in bytes WX micRoware Table 13 8 RBF Path Descriptor Options Table Structure continued Name Description pd_entl pd_wpc pd_rwr pd_park Control Word This is the control word It may currently contain the following CTRL_FMTDIS Disables formatting of the device CTRL_MULTI Device is capable of multi sector transfers CTRL _AUTOSIZE Device size can be obtained from device CTRL_FMTENTIRE Device requires only one format command CTRL_TRKWRITE Device needs a full track buffer for format Write Precompensation Cylinder This number determines at which cylinder to begin write precompensation Reduced Write Current Cylinder This number determines at which cylinder to begin reduced write current Park Cylinder This is the cylinder at which to park the hard disk s head when the drive is to be shut down Table 13 8 RBF Path Descriptor Options Table Structure continued Name Description pd_lsnoffs Logical Sector Offset This is the offset to be used when accessing a partitioned drive pd_xfersize Maximum Transfer Size This is the maximum size of memory the control
25. current DCD line state v_dcdstate 172 current path buffer position pd pbufpos 174 current process ID v_busy 164 cursor position counter pd_curpos 174 cylinders on device lu_totcyls 252 cylinders per disk pd cyl 254 CYLNDRS 262 da_execnoxfer 289 da_execute 290 data carrier detect lost flag pd lost 175 data carrier lost v_hangup SCF 159 data carrier lost flag v_hangup 161 dd_descom device descriptor common information 158 243 dd _outdev 158 ABCDEFGHIJKLMNOPQRSTUVW XYZ dd_pathopt path descriptor options 243 debugger access rombreak 23 de initialize device bt_term 278 de initialize port cons term 72 73 delete line function pd_ delete 178 SCF macro defined 194 destructive backspace flag pd _backsp 178 DEV_SPECIFICS 168 device access capabilities SCF macro defined 190 device definitions adding 198 268 device descriptor macros 188 SCF 187 device driver SCF 143 device input buffer size v_insize 165 device option definitions RBF 250 device options v_luopt 245 device specific variable macro DEV_SPECIFICS 168 device table entry address pd_deventry 180 device table pointer for echo device pd_outdev 173 device type DT_SCF 0 v_class 169 DEVTYP 261 direct access device initialize ABCDEFGHtIJKLMNOPQRSTUVWX Y Z initsccs 292 read readsccs 294 directory structure diagram 38 MWOS 12 disk booters creating 270 disk drive logical unit static storage 245 disk drive information v_driveinfo 244
26. disk driver test 228 disk formats supported pd_format 254 disk ID v_diskid 247 distribution media installation 12 DMA transfer mode lu_tfm 251 DMAMODE 263 drive unit number lu_lun 251 driver high level scllio 203 driver static storage area 231 DRIVERNAME 267 drivers low level Ethernet 77 echo flag pd_ echo 178 echo output flag pd_echoflag 174 enable transmitter interrupts SCF routines 149 ABCDEFGHIJKLMNOPQRSTUVW XYZ end of buffer position pd_endobuf 174 end of file character pd_eofch 176 end of input buffer pointer v_inend 166 end of output buffer pointer v_outend 167 end of record character pd_eorch 176 end of visible line counter pd_evl 174 entry point de install proto_deinstall 83 initiate connection proto_iconn 84 read proto_read 86 sysinit 48 terminate connection proto_tconn 88 timeout proto_timeout 89 upcall for interrupt proto_upcall 90 entry point status low level driver proto_status 87 EOLNULLS SCF macro defined 194 EOS UNKSVC 233 error count non recoverable h_harderr 248 error count recoverable v_softerr 248 Ethernet driver purpose 77 low level drivers 77 low level entry points 81 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z low level install proto_install 85 EVENTS macro 123 EXAMPLE directory start porting 15 EXTENSIONS macro 124 FD free list lock descriptor v_fd_free_rsrc_Ik 249 fdboot 284 fdman 270 RBF booter support 24 file name suffixes 13 find_n_ini
27. enum config_element_id id u_int32 index Rominfo rinf void buf pointer to configuration data module void config_data int reserved reserved for emergency expansion cnfg_svcs Cnfg_svcs If no low level system modules require the configuration services the cnfgfunc and cnfgdata modules can be omitted get_config_ data Obtain Configuration Data Element Syntax error_code enum config_element_id id u_int32 index Rominfo rinf void buf Description get_config_data returns the value of the configuration element identified by id in the caller supplied location specified by buf The following tables list the available identifiers their definition and field type size Table B 1 Console Configuration Elements Configuration Elements Description Type Size CONS_REVS structure version u_int16 CONS_NAME console name char CONS_VECTOR interrupt vector number u_int32 CONS_PRIORITY interrupt priority u_int32 CONS_LEVEL interrupt level u_int32 CONS_TIMEOUT polling timeout u_int32 CONS_PARITY parity size u_int8 CONS_BAUDRATE baud rate u_int8 KX MICROWARE Table B 1 Console Configuration Elements continued Configuration Elements Description Type Size CONS_WORDSIZE Character size u_int8 CONS_STOPBITS Stop bit u_ints8 CONS_FLOW Flow control u_ints8 Table B 2 Debugger Configuration Elements Configuration Eleme
28. I O to complete by checking the v_wake field of the logical unit static storage It sends a wakeup signal to the process specified by this field and then clears the field If the device is ready to send assuming it is servicing an output interrupt and the output buffer is empty it disables the device s ready to transmit interrupts It also flags the interrupts as disabled by clearing the OH_IROON bit and setting the OH_EMPTY bit of the v_outhalt flag field of the logical unit static storage lf a pause character is received sets the v_pause field of the logical unit static storage of the output device to a non zero value lf a keyboard interrupt or keyboard quit character is received sends the associated signal to the process specified in the v_lproc field of the logical unit static storage If an X ON or X OFF character is received enables or disables transmitter interrupts 8 If the input buffer has reached the high water mark as specified by the v_maxbuf f field of the logical unit static storage and X OFF is enabled prepares to send an X OFF character Parameters device_entry points to the device list entry WX microware READ Read Next Character Syntax error_code read Scf_path_desc path_desc Dev_list device_entry Description The READ routine for drivers that have interrupt driven input returns without error The read routine for drivers with polled input performs the same functions as a
29. Module Services The following entry points describe the services required of each low level timer module Table 6 1 Timer Module Entry Points Function Description timer_deinit De initialize timer timer_get Get the Time remaining timer_init Initialize the timer timer_set Arm the timer For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions OS 9 Porting Guide 109 O Creating a Low Level Timer Module AA micRowaRE timer_deinit De initialize Timer Syntax void timer_deinit Rominfo rinf Description Deactivate the timer Parameters rinf points to the rominfo structure f can A 110 O lt sal ld aj AUIQ oO Cc 5 9 Portin ia timer_get Get the Time Remaining Syntax u_int32 timer_get Rominfo rinf Description Determine the amount of time remaining If the time out has elapsed stop the counter and return a zero value Parameters rinf points to the rominfo structure WX microware timer_init Initialize Timer Syntax error _code timer_init Rominfo rinf Description Initialize the hardware for operation Ensure the timer is not already initialized Parameters rinf points to the rominfo structure timer_set Arm the Timer Syntax void timer_set Rominfo rinf u_int32 timeout Descri
30. Path Buffer Base Address This field points to the input buffer for the path It is the buffer associated with input and its editing functions pd_pbufpos Current Path Buffer Position This field points to the current input position in the path buffer pd_endobuf End of Buffer Position This field contains the last character position of the path buffer pd_curpos Cursor Position Counter SCF uses this field to maintain the current location of the cursor on input pd_reqent Number of Bytes Requested This field contains the total number of bytes requested on a read or readin request pd_evl End of Visible Line Counter SCF uses this field to maintain the logical end of visible line when performing the editing functions of a readin request pd_echoflag Echo Output Flag A non zero value in this field indicates echoing input is enabled Table 9 6 SCF Path Descriptor Fields continued Name Description pd_lost Data Carrier Detect Lost Flag A non zero value in this field indicates a transition of the data carrier detect line This is useful for modem support pd_opt Path Descriptor Options This field is the structure containing the path descriptor options These options are described in the following section SCF Path Descriptor Options Section The structure definition of the path descriptor options is shown here This structure is defined in the header file scf n You can update the path descriptor options using the
31. Porting Guide Windows help file included with Hawk for more information about this function Memory Services The definition of the mem_svcs structure is in the include file MWOS SRC DEFS ROM rom h typedef struct mem_svcs idver infoid id version for mem_svcs Dumb_mem rom_memlist the limited memory list Rom_list rom_romlist rom memory list Rom_list rom_bootlist boot memory list Rom_list rom_consumed memory consumed by roms Rom_list consumed_next next free consumed list entry Rom_list consumed_end last entry in consumed list u_char rom_ramlimit RAM limit highest address u_int32 rom_totram total ram found get memory u_int32 rom_malloc u_int32 size char addr Rominfo free memory rom_free u_int32 size char addr Rominfo clear memory void mem_clear u_int32 size char addr u_char rom_dmabuff 64k DMA buffer for gt 16MB systems int reserved reserved for emergency expansion mem_svcs Mem_svcs Most of the fields in the mem_svcs structure are for internal bookeeping within the raw romcore module and the rom_malloc and rom_free services The rom_bootlist entry pointer is used by booters to communicate the location and size of a boot image Table A 1 mem_svcs Functions Function Description mem_clear Clear memory rom_free Free allocated memory rom_malloc Allocate memory
32. SCF Table 9 11 SCF Macros La MICROWARE Name Description MODE MAXBUFF Device Access Capabilities This reflects the operational mode or capabilities of the device Most SCF type devices use the default value However in some cases you should change MODE to include the s_ device is non sharable For example an SCF serial printer port should be non sharable define MOI DE Sa S ZE S_IREA D S_ ISHARE bit signaling the WR TE default device mode capabilities Maximum Data for the Input Buffer This defines the high water mark of the input buffer When the input buffer reaches the defined level the sender is sent an X OFF character to temporarily halt transmission define MAXBUFF OUTS default maxbuff size ZE LOWCOUNT Table 9 11 SCF Macros continued Name Description OUTPUT_TYPE SCFBUFSI INPUT_TYPE ZE Input Type Flag This specifies whether input on the device is interrupt driven or polled If the device is operated in polled mode SCF calls the driver s read routine for every character The two values defined for this field are define IRODRIVEN 0 define POLLED 1 They are defined in scf n The default for this macro is interrupt driven define INPUT_TYPE IRQDRIVEN Output Type Flag This specifies whether output on the device is interr
33. STEP SIDE VERI S EY Step Rate This specifies the step rate to use on the RBF device The following values are commonly used Value 5 and 3 disks 8 disks 0 30ms 15ms 1 20ms 10ms 2 12ms 6ms 3 6ms 3ms Only the device driver uses the step rate value The particular driver must determine the correspondence between the step value code and the step rate used on the drive define STEP 3 Number of Heads or Sides This defines the number of heads on the drive For example a double sided floppy drive would have a SIDES value of 2 define SIDES 2 Write Verification Flag If set to a non zero value VERIFY indicates a read after write verify is desired A zero value indicates no verify should be performed It is up to the device driver to perform the verify define VERIFY 0 no verify XX microware Table 13 10 RBF Macro Definitions continued Name Description and Example FORMAT CYLNI DRS Driver Format This defines the format of the drive described by the device descriptor The definitions of the bits in the format word 16 bits are defined in rbf h de de de de de de fine FMT_DBL SID device is do fine F EIG drive is HTI fine FMT_FIV drive is fine FMT_THR drive is fine FMT_HIG fine FMT_STD FMT fine FMT_DBLTRKO 0x0001 track 0 is double density fine FMT
34. Timer Module 105 106 Creating the Timer Module 108 The Timer Services Record 109 Low Level Timer Module Services 114 Starting the Low Level Timer Module 114 Building the Low Level Timer Module Chapter 7 Creating an Init Module 117 118 Creating an init Module 119 Init 120 Macros Optional Macros Chapter 8 Creating PIC Controllers 127 128 Reviewing the PowerPC Vector Code 128 128 Architecture OS 9 Vector Code Service 132 Initialization 134 Interrupt Vector 134 136 OS 9 Technical Manual Modifying the Interrupt Vector Interrupt Controller Support WX MICROWARE Chapter 9 Creating an SCF Device Driver 139 140 141 143 143 148 158 159 168 173 175 181 183 186 187 197 197 Alternatives for Creating a Console I O Driver Creating an SCF Driver Descriptor Creating SCF Device Drivers SCF Device Driver Static Storage SCF Device Driver Entry Subroutines Using SCF Device Descriptor Modules SCF Logical Unit Static Storage SCF Logical Unit Static Storage Options SCF Path Descriptor SCF Path Descriptor Options Section SCF Control Character Mapping Table Default Mapping Table Building SCF Device Descriptors SCF Device Descriptor Macros SCF Control Character Mapping Device Specific Non Standard Definitions Chapter 10 Using Hardware Independent Drivers 201 202 203 204 204 Simplifying the Porting Process SCF Driver scllio Virtual Console iovcons Configu
35. When an exception occurs the processor saves the current program counter PC and the current machine state register MSR then transfers control to the appropriate vector The PC is loaded with the address of the vector and the MSR has the same value as before except that the applicable exception and address translation enable bits are cleared Consult the user manual for your hardware platform for specific exception processing information OS 9 Vector Code Service The standard OS 9 PowerPC vector code located in the MWOS 0S9000 SRC SYSMODS VECTORS directory is divided into two categories of service the external interrupt code and the general exception code The main difference in the two sets of vector code is the software stack used when the high level C code exception handler is called The IRQ vector code saves the current state on the current process system stack and then switches to a dedicated IRQ service stack If the system was already in an IRQ context the dedicated IRQ stack and the current system stack are the same and the vector code does not change the stack The interrupt service code continues to use the IRQ stack The general exception code uses the current process system stack throughout the context of the exception The standard exception handlers save registers r0 r14 lr ccr ctr xer srr0 and srr1 Both exception handlers use the same registers to save the context of the system and dispatch to the appropriate
36. Write a Null Terminated String To the System Console Syntax void rom_puts char OUEE Rominfo rinf Description rom_puts calls the low level write routine of the console device record configured for use as the system console rom_puts writes a null terminated string to the console device Parameters buff points to the first character of the string to output rinf points to the rominfo structure Example rinf gt cons gt rom_puts buffer rinf KX MICROWARE Notification Module Services The definition of the not ify_svcs structure resides in the include file MWOS SRC DEFS ROM rom h typedef struct notify_svcs idver infoid id version for notify_svcs handler registration service error_code reg_hndlr Rominfo rinf u_int32 priority void handler u_int32 direction void parameter void parameter u_int32 hndlr_id handler deregistration service error_code dereg_hndlr Rominfo rinf u_int32 hndlr_id notification service error_code rom_notify Rominfo rinf u_int32 direction Notify_hndlr torom_list ordered lists of handlers tosys_list empty_list empty list of available records u_int32 last_direction direction of last notification call int reserved reserved for emergency expansion notify_svcs Notify_svcs The notification services reg_hndlr and dereg_hndIir are commonly used from a low level driver requiri
37. arpinit Rominfo rinf Description arpinit function allocates memory for the ARP table and ARP buffer and initializes the buffer Parameters rinf points to the rominfo structure WX microware arpinput ARP Input Processing Routine Syntax void arpinput Proto_srvr PSrvr LIMbuf mb Rominfo rinf Description arpinput is the ARP input processing routine The routine checks for common length and type Only IP protocol packets are processes when in_arpinput is called Parameters psrvr points to the proto_srvr structure mb points to the received packet rinf points to the rominfo structure arpresolve Resolves Hardware Addresses Syntax error_code arpresolve Lipm_conn conn_entry u_char desten Description arpresolve looks into the ARP table and if successful in finding the entry for the destination address in the Llpm_conn conn_entry copies the hardware address to that destination address desten If arpresolve cannot find the entry it returns a non zero value This service is called from the proto_write routine and assumes it is always able to resolve the address without ever having to send an ARP request If however it does have to send requests it calls arpwhohas to broadcast the request In this case the proto_write function would have to be suspended until arpresolve gets a response and is able to resolve the hardware address Paramet
38. associated with this configuration are shown in Table 13 1 Table 13 1 High Level SCSI Controllers Name Handles RBTEAC TEAC SCSI floppy devices SBSCSI Archive VIPER tape device RBSCCS Hard disk device The low level module associated with this configuration is shown in Table 13 2 Table 13 2 Low Level SCSI Subroutine Module Name Handles SCSI1603 NCR53C8xx Interface on the MVME1603 CPU A conceptual map of the OS 9 modules for this system would look like this Figure 13 2 OS 9 Modules Kernel Level File Manager Level RBF disks Device Driver Level RBTEAC I RBSCCS SCSI1603 SBSCSI Physical Bus Level Perhaps the most common reconfiguration occurs when you add additional devices of the same type as the existing device For example adding an additional disk to the SCSI bus on the MVME1603 To add a similar controller Micropolis 4220 to the bus you only need to create a new device descriptor The example ports have both h0 and h1 descriptors that demonstrate the use of additional SCSI disk controller devices There are no drivers to write or modify as these already exist RBSCCI and SCS1I1603 You need to modify the existing descriptor for the RBSCCS device to reflect the second device s physical parameters such as SCSI ID and change the actual name of the descriptor itself WX micRoware Testing the Disk Driver Step 1 Step 2 Step 3 Step 4 Step 5
39. bind define PVR_DRV_USEME define PVR_BOOTDEV define PVR_MWRSVO define PVR_DRIVER define PVR_PROTOCOL define PVR_MWRSV1 define PVR_MWRSV2 define PVR_MWRSV3 define PVR_MWRSV4 For OEM User use define PVR_OEM1 define PVR_OEM2 define PVR_OEM3 define PVR_OEM4 subcodes for implementation sh define SS_IntEnable define SS_IntDisable 0x08 0x10 To indicate interface booted from 0x20 0x40 0x80 Reserved Flags for Microware for proto_rsvl field of proto_srvr 0x01 0x02 0x04 0x08 0x10 0x20 0x40 0x80 by proto_status 0x01 0x02 We might use these for distinguishing protocols drivers at some point OS 9 Porting Guide define SS_RombugOn 0x03 define SS_RombugOff 0x04 The Low Level Ethernet Driver Entry Point Services In each of the entry points of the driver module do the following Step 1 Save the current global variables pointer Step 2 Set the global variables pointer to the driver s variables when it is called before accessing them Step 3 Restore the original global variables pointer at all exit points This can be done using the swap_globals function provided in the p2lib library Table 5 1 Entry Points Function Description proto_deinstall Low level driver de installation entry point proto_iconn Low level driver initiate connection entry point proto_install Installs the low level ethernet driver prot
40. devices will you use e How are these devices mapped into memory e How is the memory organized e What does the memory map of the entire system look like Create your own working directory structure in which to design and build your port Start by creating a subdirectory in MwoS 0S9000 lt CPU Family gt PORTS lt CPU Family gt is a specific processor family directory like PPC or 80386 This is the root of your target platform s directory structure If your target platform is based ona processor for which there already exists a processor specific ports directory then your target directory can be created there instead For example if your target system is built on a PowerPC 603 CPU you could choose to develop your port in MWOS 0S9000 603 PORTS Create the necessary directories for your target and copy the following files from the corresponding directories in on the example ports as a starting point Each target port directory structure is somewhat different depending upon the configuration of the target platform BOOTS SYSTEMS PORTBOOT CMDS BOOTOBJS ROM ROM CONSCNFG makefile WX micRoware ROM COMMCNFG makefile ROM PORTMENU makefile ROM USEDEBUG makefile ROM ROMCORE RELS ROM ROMCORE makefile ROM makefile The BOOTS SYSTEMS PORTBOOT coreboot m1 file contains the list of names of modules to be merged with rom when building the boot image The makefile in ROM invokes the makefiles in each
41. example change the first line into the second line SPEC_COPTS d lt optionl gt d lt option2 gt dUSECNFGDATA SPEC_COPTS d lt optionl gt d lt option2 gt dUSECNFGDATA Modifying coreboot ml The file coreboot m1 copied from an example port contains a list of low level system modules included in the boot image when it is built To finish the configuration of your initial port use the asterisk to comment out the use of the configuration modules cnfgdata and cnfgfunc and replace the low level I O modules names in this list with the ones appropriate for your target The I O modules used in the example ports are usually named io lt device gt Porting the Boot Code KX MICROWARE Do not remove the console conscnfg of commcnfg module names and be sure to add the appropriate low level serial I O module names after console but before the conscnfg or commcnfg module names mf Note Once the new port is proven the console and communication ports can be removed if desired A WARNING Do not change the order of the low level system module names or the system may not boot CA AC Xartinn iiia 54 OS 9 Porting Guide Building the Boot Image Step 1 Step 2 Once you have ported the bootstrap code written or copied the sources and makefile for your low level serial I O modules and configured your system you are ready to build the boot image Use the makefile lt Target gt ROM makef
42. executes the SCSI command contained in cmd The adn and 11mode fields are passed down to the host adapter module from scsiman However the host adapter does not need to honor these fields since using SCSI attention or synchronized transfers during boot is not required Parameters cmd points to the SCSI command block atn is the attention flag llmode is the mode flag bdev points to the host adapter s boot dev record rinf points to the rominfo structure llinit Initializes Host Adapter Interface Syntax error_code llinit Bootdev bdev Rominfo rinf Description linit initializes the low level SCSI controller for usage Normally linit is called by the scsiman module through the l_install service Parameters bdev points to the host adapter s bootdev record rinf points to the rominfo structure XX microware llterm Terminate Host Adapter Interface Syntax error_code llterm Bootdev bdev Rominfo Fink gt Description llterm terminates usage of the host adapter module Any memory explicitly allocated for driver usage can be returned at this time Parameters bdev points to the host adapter s boot dev record rinf points to the rominfo structure Configuration Parameters Some of the standard configuration parameters recognized by the example booter modules follow Not all booters support all parameters Table 14 6 Standard Configuration Parameters Reco
43. field can be any of the following function codes OVLEFT 0x00 move cursor to the left formerly pd_bsp OVRIGHT 0x01 move cursor to the right OVBEG 0x02 move cursor to the beginning of the line OVEND 0x03 move cursor to the end of the line REPRINT 0x04 reprint the current line to cursor position TRUNCATE 0x05 truncate the line at the cursor position DELCHRL 0x06 delete character to the left CHRU 0x07 delete character under the cursor C DELWRDL 0x08 delete word to the left W WRDR 0x09 delete word to the right Ox0A delete the entire line is H z UNDEF1 0x0B undefined reserved MODETOGL 0xX0C input mode toggle type over vs insert U NDEF2 0x0D undefined reserved ENDOREC 0x0E end of record read only ENDOFILE 0x0OF end of file An editing control string or an internal SCF editing function is echoed to the terminal when this character is encountered Table 9 8 SCF Control Character Mapping Table continued Name Description size Size of Editing Function String This field specifies the size of the editing function string to echo to the terminal If this field is specified as 0 an editing function built into SCF is executed to perform the editing function If this field is non zero the string pointed to by string is echoed to the terminal string Editing Function String Pointer This field points to the ch
44. gt W define KYBDPAUSE CTRL_W Table 9 11 SCF Macros continued Name Description XON XON Function This specifies the control key to use for the X ON protocol function The default value is lt control gt Q define XON CTRL_Q XOFF XOFF Function This specifies the control key to use for the X OFF protocol function The default value is lt control gt S define XOFF CTRL_S UPC_LOCK Character Case Function This controls the casing of characters A non zero value converts input and output characters in the a z to characters inthe A z range The default value is upper and lower casing define UPC_LOCK PLOFF default to upper and lower case BSB Backspace Character Interpretation This controls how SCF interprets a backspace character as a destructive or non destructive backspace If this value is zero SCF echoes a backspace character If this value is non zero SCF echoes a backspace space backspace character sequence The default is a destructive backspace define BSB PLON default to destructive backspace XX micRoware Table 9 11 SCF Macros continued Name Description LINEDEL Delete Line Function This controls how SCF performs a delete line function A zero value causes SCF to delete a line by backspacing over it A non zero value causes a carriage return line feed sequence to be echoed to delete the line The default is a destructive line delete define LINE
45. high level driver for a floppy drive or other device can be developed Chapter 13 Creating RBF Drivers and Descriptors discusses how to create device descriptors in detail Once you know this driver works you can format a floppy disk and install an OS 9 bootfile on the floppy At this point you can create the low level driver borrowing heavily from the tested code of the high level driver to boot the system from the floppy disk Chapter 13 Creating RBF Drivers and Descriptors describes the steps necessary to create and test disk drivers c Creating low level drivers and port specific booters to boot from the various devices available on the target Chapter 14 Creating Booters discusses creating disk drivers and booters in detail OS 9 Boot Code Overview The process of booting OS 9 requires an OS 9 bootfile and boot code that initializes the system hardware locates the OS 9 bootfile and passes control to the OS 9 kernel The bootfile is a collection of the OS 9 system modules merged together into a single image with the kernel appearing as the first module This bootfile can exist in ROM RAM or flash memory On a disk based system the bootfile is on the boot disk device Tape devices can also be used as boot devices with the bootfile on magnetic tape The boot code for OS 9 contains the raw machine code bootstrap routine and a collection of separately linked but inter dependent modules organized as OS 9 extension module
46. interrupt vector code would have to build a short stack after the interrupt service routine completed and call the kernel exit routine to cause the task switch to occur Interrupt Controller Support Since the PowerPC architecture defines only one vector entry for interrupt processing it is typical for a target platform to implement one or more external interrupt controller s to control and prioritize multiple interrupts external to the processor OS 9 allows controlling code for this target dependent interrupt controller structure to be modularized independently of the standard vector dispatching code and the device drivers For More Information Refer to the OS 9 Technical Manual for more information about the _os_irq Call and interrupt polling The controlling code can be divided into two classes interrupt enable disable and interrupt acknowledge dispatch Example interrupt enable disable functions are implemented in library functions accessible to device drivers The interrupt acknowledge and dispatch functions are implemented as system extension modules that install themselves as an interrupt handler on the interrupt vector An example picirg module implements the acknowledge and dispatching code for 8259 like interrupt controllers The dispatching code in an interrupt controller module maps the interrupt line to a logical interrupt vector and then searches the interrupt polling table associated with the logical vec
47. is called within a booter s loop incrementing through each potential parameter that a booter can recognize Parameters argv points to the keyword s points to the value portion of the string kf points to the compare string ktflag is a flag 5 is an incrementer rap eg points to the rominfo structure Creating Booters Z The fdman Module Services Access to the fdman module services are through the fdman_svcs structure defined in MWOS SRC DEFS ROM fdman h Table 14 3 fdman_svcs Functions Function Description fdboot Validate bootfile get partition Locate bootable partition read_boot file Read boottfile from device For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions OS 9 Porting Guide ine CO ce WX microware E dboot Validate Boottfile Syntax error _code fdboot u_char addr u_int32 size Bootdev bdev Rominfo inf Description fdboot scans a loaded image to determine the validity of a bootfile Parameters addr is the address of the loaded image size is the address of the loaded image bdev points to the disk booter s bootdev record rink points to the rominfo structure get_partition Locate Bootable Partition Syntax error_code get_partition u_int32 u_ints8 u_int8 u_char u_int32 Bootdev Rominfo Description lsnoffs pari_st
48. micRoware Table 7 1 Init Module Override Macros from INIT default des File continued Name Description and Example SYS_PARAMS A character string containing the parameters to be passed to the first process define SYS_PARAMS n CONS_NAME A character string identifying the console terminal descriptor module name define CONS NAME term SYS_DEVICE A character string identifying the initial mass storage device descriptor module name This must be defined but can be a null string if none exists define SYS_ DEVICE Optional Macros The following describes macros that can be modified These macros do not have to be included in the N T default des file because they have default values defined in init des However if your first port does not include a ticker explained in Chapter 11 Creating a Ticker and Chapter 12 Selecting Real Time Clock Module Support then you should define the COMPAT macro with a value made up of at least the B_NOCLOCK flag Table 7 2 Init Module Optional Macros with Default Values Name Description and Example MPUCHIP OS_VERSION OS_REVISTON OS9K_REVSTR A processor specific number identifying the MPU chip for example 403 603 or 80386 define MPUCHIP 603 define MPUCHIP 80386 A number defining the version of the operating system Default value is the currently shippe
49. mleptr points to the returned module list entry pointer rinf points to the rominfo structure WX micRoware rom_modscan Scan For Modules Syntax void rom_modscan u_char modptr u_int32 hdrchk Rominfo rinf Description This service scans for contiguous modules starting at the specified address and starts them in order of occurrence When a module is not found the scan terminates rom_modscan enables low level system modules to be found in memory regions other than the base ROM area for example external ROM or flash on PCMCIA Industry Pak or other bus carriers and enables them to be configured depending on the presence or absence of that memory region Parameters modptr is the base address to scan for modules hdrchk is a flag to specify if the module header parity should be checked If the value is non zero the header parity is validated rinf points to the rominfo structure p2lib Utility Functions Three libraries are shipped as part of this distribution p2privat 1 romsys 1 p2lib 1 The p2privte l and romsys 1 libraries are only used by the bootstrap code romcore The p21ib 1 library contains functions you can use to customize your own low level system modules The p21ib 1 functions are explained in this appendix Table A 3 p21ib 1 Functions Function Description getrinf Get the rominfo structure pointer hwprobe Check a system hardware address intteascii
50. module is calculated and control is transferred to the kernel for completion of the boot Kernel Entry Point to the Shell Prompt The kernel s coldstart routine finishes the task of booting OS 9 It reads the OS 9 configuration module init and using the system configuration data stored within the kernel 1 executes all configured extension modules from the PREI initializes system global data commonly referred to as the system globals adds the colored memory list to the memory lists found by the bootstrap code builds the kernel s RAM memory from the RAM memory list builds the module directory by searching for modules in the special memory list O extensions list WX MICROWARE 6 initializes system data tables such as the path table and process table 7 opens the system console 8 changes directories to the system device 9 executes all configured extension modules from the EXTENS extension list 10 creates the first process to be executed 11 transfers control to the system execution loop to begin process scheduling The OS 9 system is now booted and executing as expected Chapter 2 Creating Target Port Directories This chapter includes the following topics lt MWOS gt 0S9000 Ports Directory Structure Creating Target Port Directories WX MICROWARE 37 KX MICROWARE lt MWOS gt 0S9000 Ports Directory Structure The following figure shows only the directo
51. more information about these functions ENABLE TRANSMITTER INTERRUPTS Enable the Device s Ready to Transmit Interrupts Syntax error_code entxirq Dev_list device_entry Description The enable transmitter interrupts routine is called by SCF and the driver when there is data in the output buffer and the v_outhalt field of the output device s logical unit static storage indicates the ready to transmit interrupts are disabled The init routine should initialize this field and the interrupt service routine s should maintain it properly Also the enable transmitter interrupts routine should flag that the transmitter interrupt is enabled by setting the OH_IROON bit of the v_outhalt field Parameters device_entry points to the device list entry WX micRoware GETSTAT Get Device Status Syntax error_code getstat I_getstat_pb ctrl_block Scf_path_desc path_desc Dev_list device_entry Description These routines are wildcard calls used to get the device parameters specified by the getstat service requests Many SCF type requests are handled by IOMAN or SCF Any get stat functions not defined by them are passed to the device driver If the function code specified in the control block is not recognized by the driver the driver returns an EOS_UNKSVC unknown service code error Parameters ctrl_block is the I_GETSTAT control block path_desc points to the path descriptor device_entry po
52. of the CPU family to which the CPU on your board belongs See Chapter 2 Creating Target Port Directories for a full description of the MWOS tree and the supported CPU directories Create a systype h file by copying it from one of the example ports directories into your working port directory This example systype h file contains comments and structure that you will use along with the explanation in Chapter 3 Porting the Boot Code to fully define the board specific definitions used throughout the porting process Phase Il Create the Low Level System Copy the bootstrap code sources from one of the example directories into your port directory and modify for the memory layout of your board Write customized startup code to initialize your board s memory and devices Chapter 3 Porting the Boot Code walks you through this process Step 4 Step 5 Step 6 WX MICROWARE Create a low level serial driver appropriate for your board s serial device using the one of the example sources and perhaps one of the drivers included in the OS 9 for Embedded Systems source library This low level serial driver provides the basic I O service to the serial hardware for displaying the OS 9 bootstrap message and resident RomBug debugging Chapter 4 Creating Low Level Serial I O Modules discusses the steps required to provide serial support for the boot code Note This overview assumes that you have a serial device on your target boar
53. point where the vectors initialization code resides The vectors are initialized by copying the exception code from the vectors module into each 256 byte vector table entry Each block of the vectors code has a unique label associated with the first and last instruction of the code These labels are used by the initialization code to copy the vectors code into the vector table entries requiring that block of code In addition to copying the vector code into the tables there are usually three other operations the initialization code must perform for most of the vectors There may be other initialization requirements dictated by the complexity of the hardware platform This description assumes the simplest case and describes what is required of the vector code 1 The first additional operation is to patch the instruction loading the vector number of the associated vector with an immediate effective address mode The target instruction is identified with a specific label the installation code can use to calculate the offset to use for the patch operation The immediate value of the target instruction is modified to contain the vector number passed to the C code handler 2 Another immediate form load instruction must be patched to contain the value of the offset of the exception table entry structure within the kernel s exception service routine table also known as the interrupt polling table for the target vector Each entry in the exception
54. rinf points to the rominfo structure sq_execnoxfer WX microware Execute a SCSI Command Without Data Transfer Syntax error_code sq_execnoxfer u_int32 opcode u_int32 blkcount u_int32 opts u_int32 action Bootdev bdev Rominfo rinf Description sq_execnoxfer issues a command to sequential devices Parameters opcode is the SCSI command code count is the size of the data transfer in blocks or bytes opts are option flags booters should use 0 action is the immediate state flag bdev points to the booter s boot dev record rinf points to the rominfo structure sq_execute Execute a SCSI Command With Data Transfer Syntax error_code sq_execute u_int32 u_int32 u_int32 u_int32 u_char u_int32 u_int32 Bootdev Rominfo Description opcode count opts action xp ff xferflags bytemode bdev Einf sq_execute issues a command to sequential devices and manages the subsequent data transfer Parameters opcode count opts action buff xferflags bytemode bdev rinf is the SCSI command code is the size of the data transfer in blocks or bytes are option flags booters should use 0 is the immediate state flag points to the data buffer specifies the data transfer direction 1 OUTPUT NPUT or indicates if the count is a block or byte count points to the booter s boot dev record points to the rominfo struct
55. saves and restores all of the registers used in the body of the handler As each C code handler is called by the dispatcher it saves and restores multiple registers in determining the need to service the exception By the time the target C code handler is located many more context preservation and restoration operations may have been performed than in the more general caller register save compiler convention This reduced context saving scheme for the vectors code should only be used under controlled circumstances where latency can be kept to a minimum and only one or two C code handlers are associated with a given exception or interrupt WX MICROWARE If this technique is used there are certain restrictions on kernel and debugger usage because a short stack frame is expected to be present under these circumstances These are 1 The debugger cannot be used to monitor the interrupt exception However breakpoints can still be processed within the interrupt service routine because they cause their own exceptions that create the short stack for debugger operations 2 The interrupt vector code after receiving control back from the interrupt service routine would directly return control back to the interrupted thread of execution itself instead of calling the kernel exit routine An exception to this would be if the interrupt service routine changed a task state that would require a task switch for example sent a signal Then the
56. service routine table is a four byte pointer to the first of a list of exception table structures associated with the vector as defined by the excpt h header file in the MWOS 0S9000 SRC DEFS directory The patch value is calculated by adding the offset of the beginning of the kernel s exception service routine table to the vector number multiplied by four This offset to the exception service routine list for the vector is patched into the vector code in order to save execution time and vector code space in dispatching to the target service routines Again each of these patchable instructions can be located within the vector table entry by using the instruction s label to calculate the offset of the instruction within the vector code The last four byte word of each vector table is patched with the offset into the associated vector the location where the OS 9 low level debugger is allowed to take over the vector In most cases this is the location of the actual b1r1 instruction dispatching to the C code handler The low level debugger uses this offset value to dynamically patch the vector code to allow itself to monitor exception and breakpoints as instructed KX MICROWARE Interrupt Vector The vector code for the interrupt vector is typically unique from the code for the other vectors Since many boards have different external interrupt control mechanisms the code handling the specifics of the interrupt control is located i
57. source file sysinit c sysinit initializes any port specific hardware devices and then branches back to the label sysreturn in bt funcs a 2 initializes the stack pointer This relies on the memory lists defined in the bootstrap source file rom_cnfg h to determine the first available RAM memory area as well as the top of stack offset into it For More Information See Chapter 3 Porting the Boot Code for information on creating the sysinit c file and the rom_cnfg h header file for your port 3 calls the sysinit1 routine in sysinit c The sysinitl routine completes the initialization of target specific hardware devices Before returning control back to bt funcs a it calls rompak1 to determine if an initext module is present for further hardware initialization initializes the bootstrap global data pointer and stack pointer This relies on the memory lists defined in the bootstrap source file rom_cnfg h to determine the first available RAM memory area initializes the bootstrap global data The callidata routine in p2privte 1 is called to initialize the global data for the bootstrap code 6 Transfers control to hard_reset in the boot c source file 7 If control is returned which only happens if it is impossible to boot the system control is transferred back to the cold label and the process repeats When boot c gets control in hard_reset it 1 initializes the vector table for the pro
58. special RAM area Bring up the system completely Use the system state debugger or ROM debugger to set breakpoints at appropriate places in the clock modules Run the setime utility to access the clock modules Repeat steps three through seven until the clock modules are operational When the clock modules are operational Step 1 Remake the init module so the B_NOCLOCKX flag is clear Step 2 Remake the bootfile to include the new init module and the desired clock modules Step 3 Reboot the system 1 2 Selecting Real Time Clock Module Support WX MICROWARE 220 OS 9 Porting Guide Chapter 13 Creating RBF Drivers and Descriptors This chapter includes the following topics Creating Disk Drivers Understanding SCSI Device Driver Differences Testing the Disk Driver Creating RBF Device Drivers Using RBF Device Descriptor Modules Building RBF Device Descriptors WX MIC ROWARE 221 KX MICROWARE Creating Disk Drivers Creating a disk driver for your target system is similar to creating a console terminal driver as explained in Chapter 9 Creating an SCF Device Driver However disk drivers are more complicated You can use a Microware supplied sample disk driver source file as a prototype If the target system has both floppy disks and hard disks create the floppy disk driver first unless they both use a single integrated controller You can create the hard disk driver after the system is up
59. storage area for each device with a unique port address The driver static storage area always contains the following five items 1 The first seven long words of the driver s dispatch table structure must contain the address of the standard driver functions SCF drivers may declare additional variables separate from this structure but it is critical that this structure be identified as the sharable portion of the driver s static storage by equating the name of the structure with the _m_share label as shown in the following example This portion of every SCF driver static storage must be the same 2 A variable used by drivers to keep track of the number of times the driver has been attached This variable can determine when to properly terminate the device 3 A pointer to the device list entry for the specific device 4 The number of interrupt service routines for the driver KX MICROWARE 5 A table of interrupt service routine entries containing the hardware vector offset of the associated interrupt and the address of the service routine completes the driver static storage wf Note SCF assumes the first interrupt entry in the table is the input interrupt service routine The static storage of the driver is a combination of the driver static storage structure and any other variables the driver declares IOMAN allocates and initializes the driver s entire static storage at attach time and also performs the follo
60. the event of a machine check an error is returned SUCCESS is returned if the read is successful Parameters addr is the specific memory address you want probed ptype is the probe type either byte word or long rinf points to the rominfo structure inttoascii Convert an Integer To ASCII Syntax char inttoascii u_int32 value char bufptr Description inttoascii converts its input value to its base 10 ASCII representation stored in bufptr The caller must ensure bufptr points to a sufficient storage space for the ASCII representation inttoascii returns bufptr Parameters value is the integer value to be converted bufptr points to the location where the ASCII value is stored WX microware outhex Display One Hexidecimal Digit Syntax void outhex u_char n Rominfo rinf Description outhex displays one hexidecimal digit on the system console The lower 4 bits of the character n are displayed using the putchar service of the system console device Parameters n is the character for which the hex value is to be displayed rinf points to the rominfo structure out Lhex Display a Hexidecimal Byte Syntax void outlhex u_char byte Rominfo rinf Description outihex displays the hexidecimal representation of a byte on the system console device Parameters byte is the byte for which the hex value is to be displayed rinf points to the rominfo struct
61. the rompak routines Wf Note Note the following e rompaki is executed prior to ROM module scan e rompak2 is executed after ROM module scan and all ROM modules have been painted e No static storage is available for the initext module The initext module is built in a ROM INITEXT subdirectory within the target port directory You should defer implementation of your base initext module until after your initial port is completed When you decide to start on your initext module use the sources and makefile from an example port as a reference KX MICROWARE Configuring the Low Level System Modules Once the bootstrap code is ported and your low level serial I O drivers are ready you need to provide some configuration data to define what your initial port looks like The OS 9 booting process relies on the use of a configuration data module cnfgdata to define certain default parameters used in the boot The configuration data module provides for great flexibility in designing your system but is not required for a simple port We recommend you keep your initial port as simple as possible If you are planning to use the Hawk remote debugger during the porting process you must use the configuration data module Read carefully about the configuration module and the low level network configuration before attempting such a port For the simple port using the target resident RomBug debugger you do not nee
62. to the sysreturn label The sysinit routine is always a complete embedded assembly routine WARNING At this point the stack register has not been initialized to point to a stack area The sysinit code must be written assuming no stack exists The sysinit1 Routine The first C routine sysinit1 completes any necessary hardware initialization that was not required to be done by the sysinit assembly routine In addition it makes the call to rompak1 to activate any initialization routines in the initext module described later in this section While a stack is present during sysinit1 execution no static storage is available The sysinit2 Routine The second C routine sysinit2 is used for any system initialization required after calling sysinit1 Often this routine consists of a routine that calls rompak2 and returns as most systems can perform all their required initialization during the first call to sysinit and sysinit1 sysinit2 is called after funcs a and boot c have e initialized the vector table for vectors in RAM and the exception jump table e performed the memory searches The sysreset Routine The third C routine sysreset is installed as a service to enable the low level system modules in particular the low level debugger a way of initiating a software reset on the target sysreset performs any WX MICROWARE special hardware actions the system requires before a
63. to a block of RAM large enough for storing e Bootstrap global data e Memory required by the low level system modules e Start up bootstrap stack e System global data If the system boots from a disk or another device the first bank needs to be large enough to also hold the size of the bootfile loaded from that device as well as any buffers required by the boot drivers The RAM memory search is performed on each area in the search list by 1 Reading the first four bytes of every 8K memory block of the area 2 Writing a test pattern sequence Memory is initialized to repetitions of the pattern Dude 0x44756465 3 Reading the area again for comparison If the read matches what was written the search assumes this was a valid RAM block and is added to the system free RAM list The Special Memory Search The second part or the special memory part of the search list is strictly a non destructive memory search This is necessary so that the memory search does not overwrite modules downloaded into RAM or NVRAM During the porting process you should temporarily include enough RAM at least 256K in the special memory list to download parts of the boot file If this download area has parity memory you may need to do one of the following e Manually initialize it e Disable the CPU s parity if possible e Include a temporary routine in the sysinit c file The RAM and special memory searches are performed by boot c duri
64. to the parser module services are through the paman_svcs structure defined in MWOS SRC DEFS ROM parse h Table 14 2 paman_svcs Functions Function Description getnum Convert numeric string to value parse_field Parse keyword equals value string from key table entry For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions AC D9Aartinan Mid OS 9 Porting Guide getnun Convert Numeric String To Value Syntax u_int32 getnum char p Description getnum converts the numeric string pointed to by the p parameter into a value and returns it Parameters p points to the numeric string WX micRoware parse_field Parse Keyword Equals Value String From Key Table Entry Syntax u_int32 parse_field char argv u_int32 s char AE int ktflag int Jy Rominfo rink Description parse_field compares the string pointed to by the kf parameter and the keyword portion of the string before the equal sign pointed to by argv If the two are not equal the service returns FALSE If they are equal and the kt flag value is 1 the service places the pointer of the value portion of the string after the equal sign into s j If they are equal and the kt flag is zero parse_field places the converted numeric value of the value portion of the string after the equal sign into s j Generally this service
65. transferring data to or from the disk device Only the device driver uses this value define DMAMODE 0 DMA transfer mode XX micRoware Table 13 10 RBF Macro Definitions continued Name Description and Example TRKOFE S BLKOFFS BLKSIZE Track Offset This defines the track offset to use when accessing the device If a track offset of one is used for example logical block 0 is the first block on side 0 of track cylinder one define TRKOFFS 1 one track offset Block Offset This defines the offset to use when obtaining the physical block number for a device A value of 1 indicates blocks are numbered from 1 to BLKSTRK A value of 0 indicates blocks are numbered from 0 to BLKSTRK 1 define BLKOFFS 1 one block offset Block Size This defines the size in bytes of the blocks used on the media define BLKSIZE 256 size of a block Table 13 10 RBF Macro Definitions continued Name Description and Example CONTROL TRYS SCSILUN PRECOMP Format Control Flags This defines the settings of various flags affecting the control of the device The definitions of the flags are defined in rbf h define CTRL_FMTDIS 0x0001 device cannot be formatted define CTRL_MULTI 0x0002 can transfer multi sectors define CTRL_AUTOSIZE 0x0004 device can find its size define CTRL_F ENTIRE 0x0008 can format entire device defin
66. 306 rom_malloc 309 rom_moddeinit 323 rom_moddel 321 rom_modinit 322 rom_modins 323 rom_modscan 315 324 rom_putc 350 rom_putchar 351 rom_puterr 352 rom_puts 353 rom_udiv 334 ROM based system 218 rombreak psuedo booter 23 romcore final binary object code 19 rominfo structure timer installation 114 rominfo structure 306 rompak1 entry point 50 rompak2 entry point 50 romsys 325 RTC_NAME macro 119 rts line state v_rtsstate 172 RTSSTATE SCF macro defined 197 ABCDEFGHtIJK LMNOPQRSTUV WX Y Z SBSCSI 226 SCF control character mapping table 181 device descriptor macros 187 device driver 143 v_busy 159 v_dcdoff 159 v_dcdon 159 v_hangup 159 v_inbufad 159 v_incount 159 v_inempty 159 v_inend 159 v_infill 159 v_inhalt 159 v_insize 159 v_irqlevel 159 v_irqmask 159 v_lockid 160 v_Iproc 159 v_lu_ num 159 v_maxbuff 159 v_opt 160 v_outbufad 159 v_outcount 159 v_outdev 159 v_outempty 160 v_outend 160 v_outfill 159 v_outhalt 159 v_outsize 159 v_pdbufsize 159 v_pdopt 160 v_pollin 159 v_pollout 159 v_priority 159 v_savirq_dv 159 v_savirq_ll ABCDEFGHIJKLMNOPQRSTUVW XYZ reserved 159 v_sigproc 159 v_use cnt 160 v_vector 159 v_wait 159 v_wake 159 vsavirq_fm 159 SCF macro defined 193 194 definitions 190 scf des SCF control character mapping 197 scf h 158 scf_desc structure 158 scf_drvr_stat 144 scf_lu_opts 168 scf_lu_stat 159 scf_path_desc 173 SCFBUFSIZE SCF macro
67. 32 u_char u_int32 u_int32 Bootdev Rominfo Description opcode blkaddr bytcnt cmdopts xp ff xferflags cmdtype bdev rinf da_execute issues a command to direct access devices and manages the subsequent data transfer Parameters opcode blkaddr bytcnt cmdopts buff xferflags cmdtype bdev rinf is the SCSI command code is the direct access device block address is the size of the data transfer in bytes are option flags booters should use 0 points to the data buffer specifies the data transfer direction INPUT or OUTPUT indicates the type of command standard or extended C1 DB_STI D OF Cl DB_EXT points to the booter s boot dev record points to the rominfo structure init_tape Initializes a Sequential Device Syntax error_code init_tape Bootdev bdev Rominfo rank Description init_tape initializes a sequential device for subsequent access Parameters bdev points to the booter s bootdev record Pink points to the rominfo structure WX microware initsccs Initializes a Direct Access Device Syntax u_int32 initsccs Bootdev bdev Rominfo Fink gt Description initsccs initializes a direct access device for subsequent access Parameters bdev points to the booter s boot dev record rink points to the rominfo structure 11_install Install a Low Level SCSI Host Adapter
68. 4 number of bytes of input buffer v_incount SCF 159 number of bytes requested pd_reqcnt 174 numeric string convert to value getnum 281 NVRAM load bootstrap image 20 open file list lock descriptor v_file_rsrc_Ik 246 open paths on device v_numpaths 249 optional ROM services 337 options section size v_optsize 169 OS_REVISION macro 121 OS VERSION macro 121 OS 9 driver 224 OS9K_REVSTR macro 121 outihex 331 out2hex 332 out4hex 333 outhex 330 output buffer address v_outbufad SCF 159 output buffer byte count v_outcount SCF 159 output buffer next in pointer v_outfill SCF 159 output buffer next out pointer outempty SCF 160 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z output buffer size v_outsize 166 output device static storage pointer v_outdev 165 SCF 159 output halt flag v_outhalt 162 output IRQ disable v_outhalt SCF 159 output type flag SCF macro defined 191 OUTPUT_TYPE SCF macro defined 191 OUTSIZE SCF macro defined 192 override override autobooting 23 p2lib 325 p2privat 325 p2start C function for timer services 114 padding characters pd_nulls 179 page pause flag pd pause 178 page pause function SCF macro defined 195 PAGEPAUSE SCF macro defined 195 PAGESIZE SCF macro defined 195 parity ABCDEFGHItIJKLMNOPQRSTUVW XYZ v_parity 171 parity of logical unitSCF macro defined 196 park cylinder pd park 256 PARKCYL 266 parse _field 282 parser 270 partition locate bootable get_partitio
69. A AR I kkk kkk RO Ram Descriptor Override Definitions J eR I AR A RA A RI A I if defined RO RO descriptor Module header macros define MH_NAME_ OVERRIDE ro Device descriptor common macros rbf macros endif RO descriptor KK K K K K K H k k H H H H H k e A KK RK RK AK k k k k A e k RK ROK RK ROKK RK KK k k k k k k k k k End of RO Ram Descriptor Override Definitions TK k k k k kk k A k k k k k k k k k k k k k k kk k kk k k k k k k k k k k k k k k k k k k k kk kkk kkk kk k KKK Standard Device Descriptor Macros This section discusses the standard macro definitions used for creating RBF device descriptors Some of the macros have predefined values you can redefine in RBF lt Driver gt config des file Others must be defined for every device descriptor Each discussion gives the name of the macro an explanation of the macro and an example definition in many cases this is the default value set by Microware These five macros are common to RBF SCF and SBF descriptors Table 13 9 RBF SCF and SBF Common Descriptors Name Description and Example PORTADDR VECTOR TROLEVEL Controller Address This is the address of the device on the bus This is the lowest address the device has mapped Port address is hardware dependent define PORTADDR Oxfffe4000 Interrupt Vector This is the vector passed to the processor at interrupt time Vector is hardwa
70. ATE XX micRoware Terminate Device Syntax error _code term Dev_list dev Description This routine is called when a device is no longer in use in the system This is defined as when the link count of its device table entry becomes zero See I_ATTACH and I_DETACH The TERM routine must 1 oo SN Wait until any pending I O has completed Disable the device interrupts Remove the device from the IRQ polling list Delete any events used by the driver Return the lock allocated by the driver in the init routine Parameters dev is the device list entry WRITE Write Sector s Syntax error code write u_int32 blks u_int32 blkaddr Rbfpd pd Dev_list dev Description The WRITE routine must D OD Oo o DoS Get the buffer address from pd_buf in the path descriptor Verify the drive number from pd_drv in the path descriptor Compute the physical disk address from the logical block number Seek to the requested physical track Write buffer s to the disk Wait for the command to complete If pd_vfy in the path descriptor is equal to zero read the data back and verify that it is written correctly We recommend that the compare loop be as short as possible to keep the necessary block interleave value to a minimum OS 9 drivers typically use the event system to wait for interrupts The driver read write routine executes an event wait and the interrupt service rou
71. Bell Character This is the bell sound character In I_READLN calls SCF echoes this character to the terminal once for every character input after the input buffer has filled It is only useful for terminals with sound capability It can be disabled by setting this value to 0 Backspace Character This is the backspace output echo character This is the backspace character SCF echoes when it is performing an editing function requiring a backspace such as move cursor left Case Mode This field indicates the casing mode SCF should use for input and output characters When this field is non zero SCF converts all characters in the range a ztoA Z KX MICROWARE Table 9 7 SCF Path Descriptor Options continued Name Description pd_backsp Destructive Backspace Flag This field indicates whether backspacing move cursor left is destructive or non destructive If it is 0 a move cursor left input control character causes SCF to echo a pd_bspch character If it is non zero SCF echoes pd_bspch space pd_bspch pd_delete Delete Line Function This field specifies how SCF implements the delete line editing function If itis 0 SCF deletes the line by backspace erasing the line If it is non zero SCF deletes the line by echoing a carriage return line feed pd_echo Echo Flag This field determines whether or not SCF echoes input characters If it is non zero SCF echoes input characters If itis 0 SCF does not echo in
72. DEL PLON default destructive delete line AUTOECHO Input Echo Function This controls whether or not input characters are echoed as they are received A non zero value causes input to be echoed A zero value flags no echoing The default is echo on define AUTOECHO PLON default to echo on AUTOLF Automatic Line Feed Function This specifies whether or not carriage returns are to be automatically followed by line feed characters The default is auto line feed on define AUTOLF PLON default to auto line feed on EOLNULLS Nulls After End Of Line This specifies the number of null 00 padding bytes to be transmitted after a carriage return line feed sequence The default value is 0 define EOLNULLS 0 default to no end of line nulls Table 9 11 SCF Macros continued Name Description PAGEPAUSE Page Pause Function This specifies whether or not the automatic page pause facility of SCF is active A non zero value causes an auto page pause upon reaching a full screen of output The default is page pause on define PAGEPAUSE PLON default to page pause on PAGESIZE Lines Per Page This specifies the number of lines per screen or page The default value is twenty four lines per page define PAGESIZE 24 default to 24 line page TABSIZE Spaces Per Tab This specifies the number of spaces per tab The default value is 4 define TABSIZE 4 default to 4 spaces tab INSERTMODE I
73. DLN calls When this field is set to 1 tick these calls return the number of characters available in the unit s input buffer pd_deventry Device Table Entry Address This field contains the address of the device table entry for the path SCF Control Character Mapping Table This table maps input control characters to the input line editing functions or user defined control strings Each entry in the field directly corresponds to the control character ASCII value in ascending order The following control characters are mapped in this table 0x01 Ox1F and Ox7F Each entry in the table has the following format typedef struct inmap_entry u_int16 type character mapping type func_code SCF editing function code u_int32 size size of associated string void string pointer to associated string inmap_entry Table 9 8 SCF Control Character Mapping Table Name Description type Mapping Type The control character mapping type can be one of three values IGNORE This control character is removed from the data stream PASSTHRU This control character is passed on without editing DFUNCTION This control character is removed from the data stream m KX MICROWARE Table 9 8 SCF Control Character Mapping Table continued Name Description func_code Editing Function Code If the type field is defined as EDFUNCTION func_code must be defined This
74. E Request to Send Flag This determines the state of the request to send line for hardware handshaking The default state is disabled define RTSSTATE RTSDISABLED default to RTS disabled SCF Control Character Mapping You can also change the input control character mapping This involves redefining the control character macro in SCF lt Driver gt config des as described previously The default input control character mapping macros are located in the scf des file Device Specific Non Standard Definitions Some SCF drivers require device specific information to be defined within the logical unit static storage structure The structure definition is needed for driver and descriptor creation in differing forms C source include file for the driver and EditMod source for the descriptor Step 1 Step 2 WX micRoware Write the EditMod form of the device specifics record and adapt the driver s makefile to Use EditMod to generate the C source include file from the EditMod source The sc85x30 example driver does this in sc85x30 des define DEV_SPECIFIC data struct device_specific_des Device specific static variables u_int 32 u_char s v_irqport device hardware irq register pointer u_int32 u_char s v_port device hardware register pointer u_char v_autovect autovector flag O chip vector l autovector sc85x30 device specific storage string drv
75. Hardware Syntax error_code _pic_disable u_int32 irgno Description _pic_disable disables the appropriate vector on the interrupt controller hardware Parameters irgno is the OS 9 vector number to disable on the PIC _pic_enable Enable Interrupt On PIC Hardware Syntax error_code _pic_enable u_int32 irqno Description _pic_enable enables the appropriate vector on the interrupt controller hardware Parameters irgno is the OS 9 vector number to enable on the PIC piclib Functions WX MICROWARE 364 OS 9 Porting Guide ABCDEFGHIJKLMNOPQRSTUVW XYZ Index Symbols _0s_irq IRQ service routine 235 _pic_disable 362 _pic_enable 363 A accumulated errors v_err 169 add devices example 227 allocatable resources list v_free 247 allocation bitmap segment information v_mapseg 247 arm timer timer_set 113 arp hardware address request arpwhohas 101 input processing and replying in_arpinput 102 input processing routine arpinput 98 low level initialize arpinit 97 resolve hardware addresses arpresolve 99 update table arptbl_update 100 arpinit arp ABCDEFGHtIJKLMNOPQRSTUVWX Y Z low level initialize 97 arpinput arp input processing routine 98 arpresolve arp resolve hardware addresses 99 arptbl_ update arp update table 100 arpwhohas arp hardware address request 101 AUTOECHO SCF macro defined 194 AUTOLF SCF macro defined 194
76. IZE Alternate serial u_int8 port word size LLPM_IF_ALT STOPBITS Alternate serial Ww Ants port stop bits LLPM_IF_ALT FLOW Alternate serial u_int8 port flow control LLPM_IF_FLAGS Interface flags u_int16 LLPM_IF_NAME Name of hardware char interface LLPM_IF_PORT_ADDRESS Replacement HW u_int32 interface address LLPM_IF_VECTOR Interrupt vector u_int32 number LLPM_IF_PRIORITY Interrupt priority u_int32 LLPM_IF_LEVEL Interrupt level u_int32 LLPM_IF_ALT_TIMEOUT Alternate serial u_int32 port timeout LLPM_IF_USE_ALT Alternate usage u_int32 flags Table B 5 Boot System Configuration Elements Configuration Elements Description Type Size BOOT_REVS Structure version u_int16 BOOT_COUNT Number of boot system u int32 configuration entries BOOT_CMDSIZE Maximum size of user input string u_int32 Table B 6 Booter Configuration Elements Configuration Elements Description Type Size BOOTER_ABNAME Abbreviated booter name char BOOTER_NEWAB Replacement abbreviated char name BOOTER_NEWNAME Replacement full name char BOOTER_AUTOMENU Auto Menu registration flag u_int8 BOOTER_PARAMS Parameter string char BOOTER_AUTODELAY Autoboot delay time in u_int32 microseconds Ld 344 Optional ROM Services KX MICROWARE Table B 7 Notification Services Configuration Elements
77. MCIA ATA PC cards FDC765 PC style floppy support Serial Communication Modules Two serial ports are used by the low level system The system console displays boot status messages error messages boot menus and debugger messages from the target resident debugger The auxiliary communications port is a download port for communicating with a host system console Target independent module providing high level I O hooks into the low level entry points of the console serial driver The available functions include getchar getc putchar putc gets and puts conscnfg Target independent module that retrieves the name of the low level driver to use for the console from the configuration data module After finding the driver on a list of available drivers conscnfg installs it as the console serial driver You can modify this module to perform target specific console configuration instead of using a cnfgdata module commcnfg 1o lt serial gt iovcons Target independent module that retrieves the name of the low level driver to use for the auxiliary communication port from the configuration module After finding the driver on the list of available drivers commen fg initializes it as the communication serial driver You could modify this module to perform target specific communications port configuration instead of using a cnfgdata module Any of the target specific low level serial drivers The low level serial dri
78. OS 9 Porting Guide Version 2 2 WX MICROWARE Intelligent Products For A Smarter World WX MIC ROWARE Copyright and Publication Information Copyright 1996 1998 Microware Systems Corporation All Rights Reserved Reproduction of this document in part or whole by any means electrical mechanical magnetic optical chemical manual or otherwise is prohibited without written permission from Microware Systems Corporation This manual reflects version 2 2 of OS 9 Revision B Publication date September 1998 Product Number 1030 0188 Disclaimer The information contained herein is believed to be accurate as of the date of publication However Microware will not be liable for any damages including indirect or consequential from use of the OS 9 operating system Microware provided software or reliance on the accuracy of this documentation The information contained herein is subject to change without notice Reproduction Notice The software described in this document is intended to be used on a single computer system Microware expressly prohibits any reproduction of the software on tape disk or any other medium except for backup purposes Distribution of this software in part or whole to any other party or on any other system may constitute copyright infringements and misappropriation of trade secrets and confidential processes which are the property of Microware and or other parties Unauthorized distributi
79. Q polling list by using the F_IRQ service request 4 If events are to be used for interrupt signaling the event should be created and its ID placed in the driver static storage Parameters dev is the device list entry IRQ SERVICE ROUTINE Service Device Interrupts Syntax error_code irq Rbf_drvr_stat drvstat Description Although this routine is not included in the device driver module branch table and is not called directly by RBF it is a key routine in interrupt driven device drivers Its function is as follows 1 Poll the device If the interrupt is not caused by this device the interrupt service routine should return with an EOS_NOTME error code 2 Service device interrupts 3 Inform the driver that the interrupt has occurred This could involve either performing an event set system call or sending a signal depending on the driver implementation If the signal method is used the interrupt service routine must clear the v_wake flag in the driver static storage area to notify the driver that the interrupt has indeed occurred When the IRQ service routine finishes servicing an interrupt it must return SUCCESS SUCCESS is defined in the const h header file tal Note The IRQ service routine is passed one parameter This parameter is specified when the driver calls _os_irq to install the service routine on the interrupt polling table This value is placed in the global pointer register
80. RK RK KK k k k k End of Sc7110 Device Default Definitions 7 FR AA AI AA A RA IA AI I kkk kk KK KKK KR RK KKK k k k A RK k k k k k ROKK ORK k k k k KK k k k k Term_t1 Sc7110 Descriptor Override Definitions descriptor for Com1 Fe AA II A I A RA IIA A I II A IR A AIR II AI AAI I A I I AAI if defined TERM_T1 Module header define MH_NAME term Device descriptor common macros define PORTADDR 0x80000480 scf macros define VECTOR 0x4c endif TERM_T1 BOK KK KK KK kkk kkk kkk kkk kkk kk I k k k k k k kkk k k k k k k k k k k k k k k k k k k k k k k k k k k k End of Term t1 Sc7110 Descriptor Override Definitions Fe FAR AA I RI A RA IA AI II A IR A IIR III A I AAI II A I Ik AAI a Usually a few fields for every descriptor type must be defined in order to make the descriptor for example port address vector IRQ level However most of the fields of the descriptor structures have pre defined values Consequently you do not need to redefine them These values seldom change from descriptor to descriptor If a change in the operational characteristics of a device is desired redefine the standard macro for the target field in config des and make the descriptor Once you have edited the config des file edit the appropriate makefile by adding the appropriate dependencies and command lines to the makefile When you have added these lines make the descriptor The following is a typica
81. S9P2 ssm A character string containing the names of the OS 9 extension modules to be executed prior to the initialization of the OS 9 I O system define PREIO picirg A character string identifying the name of the module handling I O system calls define IOMAN_NAME A number specifying the local time zone in minutes from Greenwich Mean Time Default value is 0 define SYS TIMEZONE 0 A number specifying the maximum number of signals that can be queued for a process at any given time Default value is 32 define MAX SIGS 32 Table 7 2 Init Module Optional Macros with Default Values continued Name Description and Example MEMLIST The offset to colored memory list define MEMLIST memlist MEMTBL The colored memory list define MEMTBL T Creating an Init Module WX MIC ROWARE 126 OS 9 Porting Guide Chapter 8 Creating PIC Controllers This chapter includes the following topics Reviewing the PowerPC Vector Code Initialization Interrupt Vector WX MICROWARE 127 KX MICROWARE Reviewing the PowerPC Vector Code The vector code information discussed in this section relates to PowerPC processors only See Chapter 9 Creating an SCF Device Driver if you are not using OS 9 for a PowerPC processor Architecture The PowerPC vector code consists of a table of 256 byte entries one for each vector Each entry contains the exception handling code for that vector
82. SS_PATHOPT function of the I_GETSTAT and I typedef struct scf_path_opts u_int16 pd_optsize pd_extra EX inmap_entry pd_inmap 32 u_char pd_eorch pd_eofch f pd_tabch gt pd_bellch isi pd_bspch i u_char pd_case pd_backsp pd_delete pd_echo LY pd_alf LE pd_pause Lr pd_insm u_char pd_nulls pd_page gt pd_tabsiz pd_err pd_rsvd 2 ce u_int 32 pd_col TE _SETSTAT system calls or the tmode utility path options table size reserved for future use Input control character mapping table end of record character read only end of file character tabulate character 0 none bell character for input line overflow backspace echo character case 0 both 0 upper case only backspace 0 backspace 0 backspace space backspace delete 0 carriage return line feed 0 backspace over line echo 0 no echo auto linefeed 0 no auto line feed pause 0 no end of page pause xi insert mode 0 type over 0 insert at cursor end of line null count lines per page tabulate field size most recent I O error status reserved current column number Dev_list scf_path_opts YX micRoware pd_time time out value for unblocked reads pd_deventry Device table address copy Table 9 7 SCF Path Descriptor Options Name Description pd_optsize pd_inmap pd
83. See the Using Ultra C C manual for the API global register used for your processor This variable should be a pointer to the driver static storage However the driver can use this parameter for anything useful 1 3 Creating RBF Drivers and Descriptors WX MICROWARE Parameters drvstat is the driver static storage 236 OS 9 Porting Guide READ Read Sector s Syntax error_code read u_int32 blks u_int32 blkaddr Rbfpd pd Dev_list dev Description The READ routine must Get the buffer address from pd_buf in the path descriptor Verify the drive number from pd_drv in the path descriptor Compute the physical disk address from the logical block number Seek to the physical track requested Read block s from the disk into the buffer 6 Wait for the command to finish o e o N OS 9 drivers typically use the OS 9 event system to wait for interrupts The driver read write routine executes an event wait and the interrupt service routine issues an event signal or event set to inform the driver that the interrupt has occurred Drivers can also use the more traditional sleep and signal method To do this the driver copies the current process ID from v_busy in the driver static storage to v_wake and does an indefinite sleep a sleep for 0 ticks The interrupt service routine then sends a wake up signal to the sleeping process using the ID stored in v_wake Drivers do not have to be interrupt driven A dr
84. Services 303 Configuration Parameters Appendix A The Core ROM Services 305 306 The rominfo Structure 307 Hardware Configuration Structure 309 Memory Services 314 ROM Services 315 Module Services 325 palib Utility Functions Appendix B Optional ROM Services 337 338 Configuration Module Services 345 Console I O Module Services 354 Notification Module Services Appendix C piclib l Functions 359 360 Overview Index 365 Product Discrepancy Report 405 8 OS 9 Technical Manual Chapter 1 Porting Steps Summary and Reference This guide walks you through the process of porting OS 9 to custom hardware This chapter includes the following topics Before Beginning the Port Steps Porting Steps Summary e OS 9 Boot Code Overview e OS 9 Boot Process Overview WX MICROWARE KX MICROWARE Before Beginning the Port Steps Step 1 Step 2 The OS 9 manuals use these terms for computer systems in a specific way host The development system used to edit and re compile OS 9 source files target The system to which you intend to port OS 9 The OS 9 operating system includes the OS 9 kernel init module ticker real time clock I O manager file managers device drivers device descriptors utilities and other system modules Complete the following steps before you port to your target Obtain all the documentation that came with your board Determine the following a N
85. Static Storage Fields continued Name Description v_outhalt v_lu_num Output Halt Flag This field indicates the status of output from the device SCF uses this field to decide when to call the driver s enable transmit IRQ routine to begin output Bits 2 4 are undefined Bits 5 and 6 are user definable Bits 0 1 and 7 are defined as follows Bit 0 0x01 Indicates an X OFF has been received and output has been halted Bit 1 0x02 Indicates the output buffer is empty and output has been halted Bit 7 0x80 Indicates transmitter interrupts are enabled It is important that the device driver clears this bit whenever definitions for these bits are in the scf h header file Logical Unit Number This field contains the logical unit number Note The OS 9 Configuration Reference uses v_lun Table 9 4 SCF Logical Unit Static Storage Fields continued Name Description v_wait v_irqmask v_savirg_fm v_savirq_dv v_wake I O Wait Flag This field indicates whether a process is waiting for I O on this logical unit Definitions for this field are located in the scf h header file The values of this field are defined as follows 0 No processes waiting on the device 1 A process is waiting on input to the device 2 A process is waiting on output from the device Interrupt Mask This field contains the interrupt mask used for masking interrupts to the level of the device NOTE Interrup
86. This is the vector passed to the processor at interrupt time Vector is hardware software dependent You can program some devices to produce different vectors define VECTOR 80 Interrupt Level For the Device The number of supported interrupt levels is dependent on the processor being used for example 1 7 on 680x0 type CPUs When a device interrupts the processor the level of the interrupt is used to mask out lower priority devices define IROQLEVEL 4 Table 9 10 RBF SCF and SBF Common Descriptors continued Name Description and Example R OR LUN TY Interrupt Polling Priority This value is software dependent A non zero priority determines the position of the device within the vector Lower values are polled first A priority of 1 indicates the device desires exclusive use of the vector A priority of 0 indicates the device wants to be the first device on the polling list OS 9 does not allow a device to claim exclusive use of a vector if another device has already been installed on the vector Additionally it does not allow another device to use the vector once the vector has been claimed for exclusive use define PRIORITY 10 Logical Unit Number of the Device More than one device may have the same port address The logical unit number distinguishes the devices having the same port address define LUN 2 drive number The following macros are specific to
87. VECTOR 259 SCF macro defined 188 interrupts service device 235 INTRLV 263 inttoascii 329 IOMAN_NAME_ 124 iovcons low level virtual console driver 204 IRQ polling priority ABCDEFGHIJKLMNOPQRSTUVW XYZ SCF 159 IRQ service device interrupts 235 IRQ service routine SCF 152 IRQLEVEL 259 SCF macro defined 188 keyboard interrupt character v_intr 170 keyboard interrupt function SCF macro defined 192 keyboard pause charcter v_psch 170 keyboard pause function SCF macro defined 192 keyboard quit character v_quit 170 keyboard quit function SCF macro defined 192 KYBDINTR SCF macro defined 192 KYBDPAUSE SCF macro defined 192 KYBDQUIT SCF macro defined 192 last process ID v_Iproc 164 line feed flag pd_alf 178 LINEDEL 194 lines before end of page ABCDEFGHtIJKLMNOPQRSTUVWX Y Z v_line 169 lines per page pd page 179 SCF macro defined 195 ll_install 293 Ilcmd 299 llexec 300 llinit 301 lip 77 low level IP creating 77 lltco 77 low level TCP creating 77 lIterm 302 lludp 77 logical unit input buffer size SCF macro defined 192 logical unit number LUN 260 SCF macro defined 189 v_lu_ num 162 SCF 159 logical unit options SCF structure definition 168 v_opt 168 SCF 160 logical unit output buffer size SCF macro defined 192 logical unit static storage SCF logical unit user count v_use_cnt SCF 160 logical unit user counter v_use_cnt 167 low level driver write entry point proto_write 91 low leve
88. _DBLBITDNS 0x0002 dev is double bit density fine FMT_DBLTRKDNS 0x0004 dev is double track density E 0x0008 uble sided CH 0x0010 eight inch EINCH 0x0020 five inch EEINCH 0x0040 three inch HDENS 0x1000 device is high density 0x2000 device is standard format fine F REMOVABLE 0x4000 fine FORMAT media can be removed fine FMT_HARDISK 0x8000 device is a hard disk FM FMT _STDFMT FM _DBLKTRKO FIV EINCH FMT_DBLSID Number of Cylinders This defines the number of cylinders on the drive define CYLN DRS 80 E FMT_DBLTRKDNS Table 13 10 RBF Macro Definitions continued Name Description and Example BLKSTRK Blocks Per Track This defines the number of blocks per track on the drive on all tracks but track 0 define BLKSTRK 16 BLKSTRKO Blocks Per Track 0 This defines the number of blocks per track on track 0 Some floppy disk formats use a track 0 format that is different from the rest of the media so at least track 0 can be read define BLKSTRKO 16 SEGSIZE Minimum Segment Allocation This defines the minimum number of blocks RBF should allocate when it is enlarging files define SEGSIZE 1 INTRLV Block Interleave Factor This defines the physical interleave used when formatting the disk media define INTRLV 2 DMAMODE DMA Transfer Mode This defines the type of DMA to be performed when
89. _eorch pd_eofch Path Descriptor Options Size This is the total size of the SCF path options section Control Character Mapping Table This is the input control character mapping table It maps input control characters to the input line editing functions or user defined control strings break sequences The control mapping table is described in detail following this section End of Record Character This is the end of record character the last character entered on each line for the I_READLN system call Output lines from I_WRITLN calls are terminated when this character is sent Normally the end of record character is set to SOD NOTE If the end of record character is set to 0 T_READLN calls never terminate End of File Character This is the end of file character SCF returns an end of file error for I_ READ and I_READLN system calls when this is the first and only character input It can be disabled by setting this value to 0 Table 9 7 SCF Path Descriptor Options continued Name Description pd_tabch pd_bellch pd_bspch pd_case Tab Character This is the tabulate character In I_WRITLN calls SCF expands this character to spaces to make tab stops at column intervals specified by the pd_tabsiz field NOTE SCF does not know the effect of control characters on particular terminals Therefore it may expand tabs incorrectly if they are used
90. _reserved 4 reserved for emergency expansion The following entry points describe the services required of each boot device Pseudo booters provide none of these services Table 14 1 Boot Device Entry Points Function Description bt_boot Boot from device be inic Initialize device bt_probe Probe verify device bt_read Read data from device bt_term De initialize device bt_write Write data to device For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions XX micRoware bt_boot Boot From Device Syntax u_int32 bt_boot Bootdev bdev Rominfo rinf Description This is the main entry point called by the boot system when this boot device is selected At this time any parameters can be parsed and the bt_init service is called SCSI device booters are likely to call scsiman s 11_instal1 routine to install the host adapter module Disk booters are likely to follow with a call to fdman s read_bootfile routine described later Finally bt_term is be called before returning control back to the boot system Parameters bdev points to the disk booter s bootdev record rink points to the rominfo structure bt_init Initialize Device Syntax u_int32 bt_init Bootdev bdev Rominfo rank 3 Description This routine initializes the device as necessary Param
91. al is sent to the last user of this unit It terminates the current I O request if any with an EOS_BSIG error This field is normally set to a lt control gt C character Keyboard Quit Character This field specifies the keyboard quit character When a keyboard quit character is entered a keyboard quit signal is sent to the last user of this unit It terminates the current I O request if any with an EOS_BSIG error This field is normally set to a lt control gt E character Keyboard Pause Character This field specifies the keyboard pause character When this character is entered during output output is suspended before the next end of line This also deletes any type ahead input for T_READLN X ON Character This field specifies the transmit on X ON character When this character is received output is resumed assuming it was suspended by a transmit off character NOTE X ON and X OFF are required for software handshaking for some devices Table 9 5 SCF Logical Unit Static Storage Options continued Name Description v_xoff X OFF Character This field specifies the transmit off X OFF character When this character is received output is suspended until a transmit on character is received NOTE X ON and X OFF are required for software handshaking for some devices v_baud Baud Rate This field sets the baud rate as follows 0 Hardwired 7 600 baud D 4800 baud 1 50 baud 8 1200 baud E 7200 2
92. alues are in terms of microseconds though the counter resolution for a timer does not need to be that small If the counter resolution is greater than a microsecond the timer services would have to guarantee at least the specified time had elapsed perhaps rounding up to the next value given the counter resolution It is not generally advisable to use the same device for the system ticker as for the low level timer However under some circumstances it may be done For More Information See Chapter 11 Creating a Ticker for more information about tickers An example of a software timer can be found in the MwoS SRC ROM TIMERS SWTIMER directory This example needs to be calibrated to the target platform given a fixed CPU speed and caching configuration The software timers have no upper bound on elapsed time but the specified time must have elapsed You may be able to configure and use the source code for one of the included example low level timer modules without modification If your target has a counter timer for which no timer module already exists use the example sources as a guide to write your own timer module The low level timer module sources are in the MWOS SRC ROM TIMERS directory Create a subdirectory for your own source code if you are writing your own timer module Try to keep your source specific to the particular counter device and not introduce target specific constants Figure 6 1 Creating a Ne
93. and running on the floppy A test disk must exist with the correct type of OS 9 formatting If you are using an OS 9 based host system you can make test disks on the host system e across development system you should obtain sample pre formatted disks from Microware You should make a non interrupt driver the first time to make your debugging task easier Make a new download file that includes the disk driver and descriptor modules along with one or two disk related commands such as dir and free for testing If you are using the RomBug include the driver s stb module for easier debugging You can add the previously tested and debugged console driver and descriptor modules to your main system boot at this time This minimizes download time as in the previous step Disk drivers make use of the RBF file manager The Random Block File Manager RBF is a re entrant subroutine package for I O service requests to random access devices Specifically RBF is a file manager module supporting random access block oriented mass storage devices disk systems bubble memory systems and high performance tape systems RBF can handle any number or type of such systems simultaneously It is responsible for maintaining the logical and physical file structures When you write a device driver do not include MPU CPU specific code This makes the device driver portable For More Information Refer to the OS 9 Technical Manual for mor
94. aracter string to be echoed to the terminal Default Mapping Table The following control character mappings are defined in scf des They are used whenever a new device descriptor is created Table 9 9 SCF Default Mapping Function Identifier Function Type Code Size String 0x01 lt CTRL gt A EDFUNCTION MOVEND 0 NULL 0x02 lt CTRL gt B EDFUNCTION MOVLEFT 0 NULL 0x03 lt CTRL gt C IGNORE 0 0 NULL 0x04 lt CTRL gt D EDFUNCTION DELCHRU 0 NULL 0x05 lt CTRL gt E IGNORE 0 0 NULL KX MICROWARE Table 9 9 SCF Default Mapping continued Function Identifier Function Type Code Size String 0x06 lt CTRL gt F EDFUNCTION MOVRIGHT 0 NULL 0x07 lt CTRL gt G PASSTHRU 0 0 NULL 0x08 lt CTRL gt H EDFUNCTION DELCHRL 0 NULL 0x09 lt CTRL gt I EDFUNCTION MODETOGL 0 NULL OxOA lt CTRL gt J PASSTHRU 0 0 NULL OxOB lt CTRL gt K EDFUNCTION TRUNCATE 0 NULL OxO0C lt CTRL gt L EDFUNCTION DELWRDL 0 NULL OxOD lt CTRL gt M EDFUNCTION ENDOREC 0 NULL OxOE lt CTRL gt N PASSTHRU 0 0 NULL OxOF lt CTRL gt O PASSTHRU 0 0 NULL 0x10 lt CTRL gt P EDFUNCTION REPRINT 0 NULL 0x11 lt CTRL gt Q IGNORE 0 0 NULL 0x12 lt CTRL gt R EDFUNCTION DELWRDR 0 NULL 0x13 lt CTRL gt S IGNORE 0 0 NULL 0x14 lt CTRL gt T PASSTHRU 0 0 NULL 0x15 lt CTRL gt U PASSTHRU 0 0 NULL 0x16 l
95. are Parameters vector is the number of the exception for which the handler should be installed ingsve points to the exception handling code you want installed rinf points to the rominfo structure WX microware swap_globals Exchange Current Globals Pointer Syntax u_char swap_globals u_char new_globals Description swap_globals replaces the caller s global data pointer with a new value and returns the old value Parameters new_globals is the value to be assigned to the global data pointer Appendix B Optional ROM Services There are several optional categories of service for a final production boot ROM which can be implemented according to your desired configuration Since these services are modularized they may be left out to conserve required ROM and RAM space or be included to meet a functional requirement This appendix includes the following topics Configuration Module Services e Console I O Module Services e Notification Module Services WX MICROWARE KX MICROWARE Configuration Module Services The configuration services module cnfgfunc provides access to data built into the configuration data module The definition of the cnfg_svcs Structure resides in the include file MWOS SRC DEFS ROM rom h and appears here for illustration typedef struct cnfg_svcs idver infoid id version for cnfg_svcs configuration service error_code get_config_data
96. art pari_end sectO OfES bdev Fink get_partition finds the first bootable partition on the disk within the specified partition range Parameters lsnoffs pari_start pari_end secto offs bdev rinf is the original logical sector offset of the drive is the starting partition number to scan is the ending partition number to scan points to the sector zero buffer points to the partition offset pointer points to the disk booter s bootdev record points to the rominfo structure read_bootfile WX microware Read Bootfile From Device Syntax error_code read_boot file u_int32 ssize u_int32 lsnoffs u_int8 pari_start u_int8 pari_end Bootdev bdev Rominfo rinf Description read_bootfile attempts to read in the first bootfile found on the disk within the specified partition range Parameters ssize is the sector size of the disk lsnoffs is the original logical sector offset of the drive pari_start pari_end bdev rine is the starting partition number to scan is the ending partition number to scan points to the disk booter s bootdev record points to the rominfo structure The scsiman Module Services Access to the scsiman module services are through the scsi_svcs structure defined in MWOS SRC DEFS ROM scsiman h Table 14 4 scsi_svcs Functions Function Description da_execnoxfer da execute init_tape inicsccs Li ee ey readsecs re
97. at file from the communications port and loads it into memory Target independent booter support module that assists in reprogramming flash memory flashb relocates the console downloader and flash programming modules from flash memory to RAM This enables a new booter to overwrite that flash memory location flashb calls the flash specific module to program each sector and optionally calls a downloader module to read data for programming into flash memory Target independent booter module that locates the OS 9 bootfile in the special memory list Like all booters romboot installs itself on the list of available booters when initialized Target independent booter module that restarts the boot process if it is called Target independent pseudo booter meant to drop the system into the configured system state debugger Target independent booter support module providing argument value pair parsing services XX micRoware fdman Target independent booter support module providing general booting services for RBF file systems peman Target independent booter support module providing general booting services for PCF file systems PC FAT file systems scsiman Target independent booter support module providing general SCSI command protocol services lt low level SCSI module gt Target specific booter support module providing SCSI host adaptor access services IDE Target specific standard IDE support including PC
98. ates this field when it removes characters from the input buffer Beginning of Input Buffer Pointer This field contains a pointer to the beginning of the input buffer for this logical unit XX micRoware Table 9 4 SCF Logical Unit Static Storage Fields continued Name Description v_infill v_inempty v_inend v_outsize v_outcount v_outbufad Next Data Input Pointer to Input Buffer This field contains a pointer to the next in position for the input buffer for this logical unit The device driver uses and maintains this pointer to place characters in the input buffer Next Data Output Pointer from Input Buffer This field contains a pointer to the next out position for the input buffer for this logical unit SCF uses and maintains this pointer to remove characters from the input buffer End of Input Buffer Pointer This field contains a pointer to the end of the input buffer for this logical unit Output Buffer Size This field contains the size of the output buffer for this logical unit Current Byte Count in Output Buffer This field contains the number of bytes currently in the output buffer SCF updates this field as it places characters in the output buffer The device driver updates this field as it removes characters from the output buffer Beginning of Output Buffer Pointer This field contains a pointer to the beginning of the output buffer for this logical unit Table 9 4 SCF Logical Unit St
99. atic Storage Fields continued Name Description v_outfill v_outempty v_outend v_lockid v_use_cnt v_pdopt Next Data Input Pointer to Output Buffer This field contains a pointer to the next in position for the output buffer for this logical unit SCF uses and maintains this pointer to place characters in the output buffer Next Data Output Pointer from Output Buffer This field contains a pointer to the next out position for the output buffer for this logical unit The device driver uses and maintains this pointer to remove characters from the output buffer End of Output Buffer Pointer This field contains a pointer to the end of the output buffer for this logical unit Resource Lock ID This field contains the resource lock identifier for this logical unit SCF uses this field to arbitrate exclusive access to this logical unit Logical Unit User Counter This field can be used by the driver to record the number of users using a given logical unit This provides better control over devices supporting more than one unit Path Descriptor Option Pointer This field contains a pointer to the path descriptor options section for this path KX MICROWARE Table 9 4 SCF Logical Unit Static Storage Fields continued Name Description v_opt Logical Unit Options This field is the structure containing the logical unit options for this logical unit These options are described follow
100. automatic line feed function SCF macro defined 194 B NOCLOCK 217 218 debugging tick timer 216 restart tick timer 211 with os _setime 212 216 backspace character pd_bspch 177 backspace character interpretation SCF macro defined 193 baud rate 11 SCF macro defined 196 v_baud 171 BAUDRATE SCF macro defined 196 beginning of input buffer pointer v_inbufad 165 beginning of output buffer pointer ABCDEFGHIJKLMNOPQRSTUVW XYZ v_outbufad 166 bell character pd_bellch 177 bits per character SCF macro defined 197 v_wordsize 172 BLKOFFS 264 BLKSIZE 264 BLKSTRK 263 BLKSTRKO 263 block 0 read flag v_zerord 249 block logical size pd_bsize 255 blocks tracks for track zero pd t0b 254 blocks tracks per track pd_blk 254 boot from device bt_boot 274 bootcode steps to boot OS 9 20 bootdev 270 available boot devices 272 booter rombreak 23 support pcman 24 bootfile read from device read_bootfile 286 validate fdboot 284 BOOTLIST coreboot ml file 40 bootstrap code defined 19 broadcast address determination in_boradcast 104 BSB 193 bt_boot 274 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z bt_data 270 bt_init 275 bt_probe 276 bt_read 277 bt_term 278 bt_write 279 byte ordering flag v_endflag 249 cache data lock descriptor v_crsrc 248 cache data pointer v_cache 248 case mode pd case 177 character case function SCF macro defined 193 clock modules debugging disk based system 217 real time su
101. be delivered to the low level driver 11tcp and 1ludp communicate with the protoman module handling the protocol services to communicate with network booters virtual consoles and debugger modules This chapter includes the following topics Creating a Low Level Ethernet Driver e Required Ethernet Driver Functions e Additional Utility Functions Low Level ARP e Other Functions WX MICROWARE KX MICROWARE Creating a Low Level Ethernet Driver Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Use the following steps to create a low level Ethernet driver Obtain information about the Ethernet chip on the target board e Get data book from the manufacturer e Obtain packet drivers for the chip to test out on a PC Several packet driver collections are available on the World Wide Web on FTP sites and by mail e Obtain a reference board with the supported chip e Determine the chip s memory management map for mbufs e Determine how the information is transmitted for example in a circular buffer or FIFO buffer Review the supplied example Ethernet drivers to find the one that most closely fits the capabilities and requirements of the Ethernet chip on your target board For an example Ethernet driver see the 1121040 file in the lt MwosS gt SRC ROM PROTOCOLS directory Edit the example you selected to include the information specific to the target Ethernet chip See Required Ethernet Driver Funct
102. ble interrupt controllers Create a library of calls that access your PIC s to provide a transparent way for drivers to enable disable interrupts on your board Refer to Chapter 8 Creating PIC Controllers for detailed information on these steps Write a high level serial driver for use as your system console Chapter 9 Creating an SCF Device Driver walks you through the details If you would rather avoid writing a high level driver for the initial board port see Chapter 10 Using Hardware Independent Drivers If you complete the previous steps you have completed a port to your target board The OS 9 shell should run on your target board as a single tasking operating system Complete the following step to add multi tasking and time slicing to the basic port Create a system ticker to enable time slicing and multi processing See Chapter 11 Creating a Ticker for more details WX MICROWARE Phase V Adding Features to the Basic Port The amount of work required to complete your port depends on the number and types of devices present on your board Step 12 Perform any additional porting steps including a Creating more high level drivers for other serial ports clocks and any other available devices Clock creation and debugging is explained in Chapter 12 Selecting Real Time Clock Module Support b Creating high level drivers for disk devices Once the basic port of a board has been completed the first two port procedures a
103. called it attempts to link to the tick timer module name specified in the init module If the tick timer module is found the module s entry point is called to initialize the tick timer hardware An alternative is to clear the B_NOCLOCK bit of the compatibility flag in the init module If this bit is cleared the kernel automatically starts the tick timer during the kernel s cold start routine This is equivalent to asetime s For More Information Refer to the Utilities Reference manual for information about using setime or the OS 9 Technical Manual for information about _os_setime KX MICROWARE Debugging the Ticker The kernel can automatically start the system clock during its coldstart initialization The kernel checks the init module s m_compat word at coldstart If the B_NOCLOCK bit is clear the kernel performs an _os_setime system call to start the tick timer and set the real time This automatic starting of the clock can pose a problem during clock driver development depending on the state of the real time clock hardware and the modules associated with the tick timer and real time clock If the system software is fully debugged you should not encounter any problems The following is a common scenario if you have not already created a real time clock The system has a working tick module but no real time clock support If the B_NOCLOCK bit in the init module s m_compat byte is clear the kernel
104. cation modules and a network driver for remote system state debugging both before and after OS 9 is up and running Once the OS 9 system has booted you can use either high level networking drivers and protocols SPF for example or low level communications to perform remote user state debugging on the target The high level drivers and protocols do not use the same communications path as the low level communications Regardless of the communications path if the system drops into system state the low level drivers protocols must be used to communicate with the host Some low level system modules require that they be informed when a transition takes place between high and low level states in order to do special maintenance WX MICROWARE The notify module provides the following services Table 1 2 notify Module Services Service Description Registration Any low level system module requiring notification of a state change can call notify The calling module passes the address of a routine to be called in the event of such a state change and the registration routine includes it on a list of such routines to be called De registration A low level system module can call notify to cause its routine to be removed from the list of routines to be called in the event of a state change Notification The debugger calls notify when a state change takes place notify passes over its list of routines requiring notification and call
105. cessor This is done through a call to the initvects routine in the cbt funcs c file determines the processor type and floating point unit fpu type These are calls to get fpu and getcpu inbtfuncs a searches for and initializes the low level system modules through a call to rominfo_control in romsys 1 The rominfo record structure is initialized then the memory immediately following the bootstrap code is searched for valid contiguous low level system modules and each one that is found is initialized During initialization the low level system modules add tables and pointers to their services onto the rominfo record structure performs RAM and special memory searches and if needed enables memory parity checking The memory search routines use both bus errors and pattern matching to determine the sizes of valid RAM and ROM memory segments available on the system This relies on the memory list defined in rom_cnfg h to determine the memory areas to search inserts the bootstrap global data area and stack area into the consumed memory list KX MICROWARE 6 Calls the sysinit2 routine in sysinit c The sysinit2 routine performs any target specific initialization that relies on the completion of the previous steps There may not be any but before sysinit2 returns it calls rompak2 to determine if an initext module is present for further target specific initialization 7 Initiates the configured low level deb
106. cks Per Second This value is derived from the count value placed in the tick timer s hardware counter It reflects the number of tick timer interrupts occurring each second Most systems set the tick timer to generate 100 ticks per second but you can vary it A slower tick rate makes processes receive longer time slices making multitasking appear sluggish A faster rate may burden the kernel with extra task switching overhead due to increased rate for swapping of active tasks Ticks Per Time Slice This parameter is stored in the init module s m_slice field It specifies the number of ticks occurring before the kernel suspends an active process The kernel checks the active process queue and activates the highest priority active task The init des module sets this parameter to a default value of 2 but this can be modified by defining the SLICE macro in the default des file to the desired value define SLICE 2 ticks per time slice Tick Timer Module Name The name of the tick timer module is specified in the init module Use the TICK_NAME macro in the default des file in the INIT directory to define this name For example define TICK_NAME tk8253 Tick Timer Activation You must explicitly start the tick timer to allow the kernel to begin multitasking This is usually performed by the set ime utility or by an _os_setime system call during the system startup procedures When _os_setime is
107. ctrltype interrupt controller type cpu386 struct cpuppc_config idver infoid id version for hw_config u_int32 cc_cputype specific cpu type cc_fputype specific fpu type cc_intctrltype interrupt controller type cpuppe cpu cache flushing routine void flush_cache u_int32 addr u_int32 size u_int8 type Rominfo rinf int reserved reserved for emergency expansion hw_config Hw_config Of the CPU specific configuration fields generally only cputype and fputype are currently used The other fields are provided for future use The flush_cache service is provided by a separate module 1shcach that only needs to be installed if caching is available and expected to be active The debugger and other modules that build code segments at runtime require this service WX microware flush_cache Flush the Caches Syntax u_int32 flush_cache u_int32 addr u_int32 size u_int8 type Rominfo rinf Description Flush the specified cache region Parameters addr points to the region of memory to flush size is the size of the region of memory to flush If zero all cache tables are to be flushed type is the type of cache to be flushed if applicable The available values are HW_CACHETYPE_INST instruction cache HW_CACHETYPE_DATA data cache rink points to the rominfo structure For More Information Refer to the OS 9
108. d Optional Phase Ill Set Up Hawk System State Debugging If you want to use sndp or Hawk system state debugging instead of RomBug for the remainder of your port proceed with Step 5 If you would rather continue using RomBug for system state debugging skip to Step 8 Create a second serial port or an Ethernet port driver to use as the communications link for debugging e To create a low level serial driver see Chapter 4 Creating Low Level Serial I O Modules e To create a low level Ethernet driver see Chapter 5 Creating a Low Level Ethernet Driver Create a low level timer module to support Hawk debugging communications Chapter 6 Creating a Low Level Timer Module discusses this issue in detail Step 7 Step 8 Step 9 Step 10 Step 11 Configure and test Hawk by including the following components in the boot module list and verifying the Hawk connection a The Hawk support modules b The low level serial or Ethernet driver c The low level timer For More Information See Using Hawk for information on configuring Hawk Phase IV Create the High Level System Create an initial Init module and boot image with she11 as the first executable process and term as the system console for debugging purposes Chapter 7 Creating an Init Module discusses the Init module in detail optional Create a PIC driver for each programmable interrupt controller on your board if your board uses programma
109. d version define OS_VERSION 2 version 2 x A number defining the revision of the operating system Default value is the currently shipped revision define OS REVISION 0 rev x 0 A processor specific character string identifying the operating system define OS9K_REVSTR OS 9000 PowerPC tm define OS9K_REVSTR OS 9000 V2 1 for Intel x86 A customer defined number An example of the use of this number would be to denote the location where the operating system was installed Default value is 0 define SITE 0 WX microware Table 7 2 Init Module Optional Macros with Default Values continued Name Description and Example PROCS A number specifying the initial number of entries in the process table Must be divisible by 64 Default value is 64 define PROCS 64 PATHS A number specifying the initial path table size Must be divisible by 64 Default value is 64 define PATHS 64 SLICE Is the number of clock ticks for each process time slice The actual duration for a time slice is this number times the tick rate Default value is 2 define SLICE 2 SYS_PRIOR A number defining the priority of the initial process Default value is 128 define SYS_PRIOR 128 MINPTY A number defining the system minimum executable priority See the OS 9 Technical Manual for a explanation of priority Default value is 0 define MINPTY 0 MAXAGE A numb
110. d 166 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z input buffer end of buffer pointer v_inend SCF 159 v_infill 166 SCF 159 v_inhalt 161 SCF 159 v_init 145 249 v_insize 165 SCFf 159 v_intr 170 v_irqcnt 147 v_irqlevel 160 244 SCF 159 v_irqmask 163 SCF 159 v_irqrins 147 v_line 169 v_lockid 167 SCF 160 v_Iproc 164 SCF 159 v_lu_num 162 SCF 159 v_luopt 245 v_mapseg 247 v_maxbuff 165 SCF 159 v_numpaths 249 v_opt 168 SCF 160 v_optsize 169 v_outbufad 166 SCF 159 v_outcount 166 SCF 159 v_outdev 165 SCF 159 v_outempty 167 SCF 160 v_outend 167 ABCDEFGHtIJKLMNOPQRSTUVW XYZ output buffer end of buffer pointer v_outend SCF 160 v_outfill 167 SCF 159 v_outhalt 162 SCF 159 v_outsize 166 output buffer size v_outsize SCF 159 v_parity 171 v_pause 169 v_pdbufsize 165 SCF 159 v_pdfbufsizef SCF 159 v_pdopt 167 SCF 160 v_pollin 160 SCF 159 v_pollout 161 SCF 159 v_priority 160 244 SCF 159 v_psch 170 v_quit 170 v_read 145 v_reserved 245 250 v_rsrvd 147 v_rtsstate 172 v_savirq_dv 163 SCF 159 v_savirq_fm 163 SCF 159 v_savirq_ll SCF reserved 159 v_setstat 146 v_sigproc 164 SCF ABCDEFGHtIJKLMNOPQRSTUVWX Y Z array 159 v_softerr 248 v_stopbits 172 v_terminate 146 v_trak 248 v_use cnt 167 SCF 160 v_vector 244 SCF 159 v_wait 163 SCF 159 v_wake 163 SCF 159 v_wordsize 172 v_write 145 v_xoff 171 v_xon 170 v_zerord 249 VECTOR 259 SCF macro defined 188 vector code architecture 128 initialization 132 reg
111. d a configuration module Configuring the simple port involves 1 Adding to systype h the definitions the low level system modules use as default configuration values for system console and communications ports 2 Modifying the boot module makefiles to disable use of the configuration data module for the first port stage 3 Modifying the boot module list found in coreboot m1 to reflect the low level system modules required for your system Adding Configuration Information to systype h systype h should be modified to include definitions for the symbols CONSNAME and COMMNAME The symbol CONSNAME gives the name of the console device record that the console configuration module conscnfg will by default select for use as the system console Similarly COMMNAME is used by commcnfg as the default for the communication port For example define CONSNAME COMM1 NAME define COMMNAME MVME1603 com2 Modifying Low Level System Module makefiles For your initial port disable use of the configuration data module Later chapters discuss how to build and use this module Modify each of the following makefiles copied earlier from an example port lt Target gt ROM COMMCNFG lt Target gt ROM CONSCNFG lt Target gt ROM PORTMENU lt Target gt ROM USEDEBUG These makefiles contain the definition of a macro called SPEC_COPTS that is defined to include the C option dUSECNFGDATA Comment this option out of the macro definition For
112. d see the following display Shell Try to run the dir utility If this fails begin debugging by repeating this procedure with breakpoints inserted in the driver s INIT GETSTAT SETSTAT and READ routines during Step 8 KX MICROWARE Creating RBF Device Drivers RBF type device drivers support any random access storage device that reads and writes data in fixed size blocks for example disks or bubble memories The file manager handles all file system processing and passes the driver a data buffer and a logical block number LBN for each read or write operation Write calls to the driver initiate the block write operation and if required a prior seek operation For interrupt driven systems the controller generates an interrupt when the data has been written from the buffer on to the disk The driver must suspend itself until the interrupt occurs DMA operation is preferred if available If the verify flag is set in the path descriptor pd_vfy the block should be read back and verified Drivers for hard disks are relatively simple for two reasons e The driver typically works with an intelligent controller e The disk format is fixed For example most SCSI type hard disk controllers directly accept OS 9 s logical sector number as the physical sector address Floppy disk drivers are more complicated They work with less capable disk controllers and often must handle a variety of disk sizes Disk driver
113. ddress Is a Broadcast Address Syntax int in_broadcast LLpm_conn conn_entry Description in_broadcast determines if the destination address in the Llpm_conn pointed to by conn_entry is a broadcast address This does not handle subnetting however The function returns a non zero value if the address is a broadcast address and a zero value SUCCESS if not Parameters conn_entry is not used in the drivers but is present because the protocols also use the same prototypes This entry point is called by hlproto to turn on off the interrupts It is also called by the notification handler routine Chapter 6 Creating a Low Level Timer Module This chapter includes the following topics Creating the Timer Module The Timer Services Record Low Level Timer Module Services Starting the Low Level Timer Module WX MICROWARE 105 KX MICROWARE Creating the Timer Module A timer module is required whenever timing services are required The following list includes examples of when you should use a timer module e Low level network protocols are being used for booting e An autobooter has been configured with a specified delay e User state Hawk debugging must be done using low level communications e The high level driver is scl1lio and it is operating in interrupt driven mode Low level timers are polled instead of interrupt driven A simple programmable counter is usually adequate The timer services v
114. defined 191 scfdesc h control character mapping table 183 scllio high level driver 203 initial port communications 203 using for console device directory tocopy 140 SCS execute command da_execnoxfer 289 da_execute 290 SCSI command execute Ilcmd 299 llexec 300 sq_execnoxfer 296 sq_execute 297 SCSI controller ID lu_ctririd 251 SCSI host adaptor ABCDEFGHtIJKLMNOPQRSTUVWX Y Z install ll_install 293 scsi_svcs 287 SCSI1603 226 SCSILUN 265 scsiman 270 SCSI booter support 24 sector base offset pd_boffs 255 sector interleave factor pd_ilv 255 sector logical offset pd_Isnoffs 257 segment allocation size pd sas 255 SEGSIZE 263 set device status RBF 239 setexcpt 335 setime utility 211 SETSTAT RBF 239 SCF 155 SIDES 261 signal process information for data ready v_sigproc 164 signal process information for DCD false v_dcdoff 164 signal process information for DCD true v_dcdon 164 SITE macro 121 size of input buffer v_insize SCF 159 SLICE macro 122 spaces per tab SCF macro defined 195 special memory 47 special memory areas 45 sq_execnoxfer 296 sq_execute 297 ABCDEFGHIJKLMNOPQRSTUVW XYZ srecord boots S record files 23 SS_DCOFF process to signal v_dcdoff 159 SS_DCON process to signal v_dcdon 159 SS_RESET 239 SS_SENDSIG process to signal v_sigproc 159 SS_WTRK 239 startup initmodule 118 STEP 261 step 1 create PORT directories 15 step 10 console driver 17 step 11 create syste
115. e Set the step rate to the fastest value the drive is capable of to reduce access time These are the values commonly used 0 STEP_30MS 1 STEP_20MS 2 STEP_12MS 3 STEP_6MS lu_tfm DMA Transfer Mode This is hardware specific If available the byte can be set for use of DMA mode DMA requires only a single interrupt for each block of characters transferred in an I O operation It is much faster than methods that interrupt for each character transferred lu_lun Drive Unit Number lu_ctrlrid This number is used in the command block to identify the drive to the controller The driver uses this number when specifying the device SCSI Controller ID This is the ID number of the controller attached to the drive The driver uses this number when communicating with the controller WX microware Table 13 7 RBF Disk Device Option Structure continued Name Description lu_reserved lu_totcyls Reserved for Future Enhancements Cylinders On Device This value is the actual number of cylinders ona partitioned drive The driver uses this value to correctly initialize the drive Path Descriptor Options Table The structure definition of the RBF path descriptor options is shown here This structure is defined in the header file rof h typedef struct rbf_path_opts rbf_path_opts u_int32 pd_sid pd_vfy pd_format pd_cyl pd_blk pd_t0b pd_sas pd_ilv pd_toffs pd_boffs pd_trys pd_bsize pd_en
116. e rom_getchar reads a character from the console XON or XOFF characters not processed by the low level read are ignored If echoing is enabled for the console rom_getchar calls putchar to echo this character The character is then returned by rom_getchar Parameters rinf points to the rominfo structure Example ch rinf gt cons gt rom_getchar rinf rom_gets Read a Null Terminated String From the System Console Syntax char rom_gets char OUT 7 u_int32 count Rominfo rinf Description rom_gets calls the low level read routine of the console device record configured for use as the system console rom_gets reads a null terminated string from the console into the buffer designated by the pointer buff The rudimentary line editing feature of lt backspace gt is supported by rom_gets rom_gets returns to the caller when it receives a carriage return character 0x0d or when the number of characters designated by count has been read Parameters buff points to the input buffer into which the string is read count is the integer used as the size of the input buffer including the null termination rinf points to the rominfo structure Example str rinf gt cons gt rom_gets buffer count rinf XX microware rom putc Output One Character Syntax void rom pute char on Rominfo rink Consdev cdev Description rom_putc calls the low level wri
117. e CTRL_TRKWRITE 0x0010 do track writes for format define CONTROL CTRL_MULTI control word Number of Retries Before Error This defines the number of retries that should be performed before returning an error define TRYS 7 SCSI Logical Unit Number This defines the SCSI logical unit number to be used by a device Only the device driver uses this value It can be used for things other than the SCSI logical unit number in the case of non SCSI drivers define SCSILUN 2 First Cylinder for Write Precompensation This defines the starting cylinder for write precompensation Only the driver uses this value define PRECOMP CYLNDRS XX micRoware Table 13 10 RBF Macro Definitions continued Name Description and Example RE DWRI TE PARKCYL LSNOFFS TOTCYLS First Cylinder for Reduced Write Current This defines the starting reduced write current cylinder Only the driver uses this value define REDWRITE CYLNDRS Park Cylinder This defines the cylinder where the read write heads of the drive should be placed when an _os_ss_sqd setstat is performed Only the driver uses this value define PARKCYL 0 Logical Block Offset This defines the logical block offset to be used when accessing the device This value is added to the logical block address RBF passes to the driver Only the driver uses this value define LSNOFFS 1
118. e density FMT_DBLBITDNS Device is double bit density FMT_DBLTRKDNS Device is double track density FMT_DBLSIDE Device is double sided FMT_EIGHTINCH Drive is eight inch FMT_FIVEINCH Drive is five inch FMT_THREEINCH Drive is three inch FMT_HIGHDENS Device is high density FMT_STDFMT Device is standard format FMT_REMOVABLE Media can be removed FMT_HARDISK Device is a hard disk pd_cyl Cylinders This is the number of cylinders per disk pd_blk Blocks Track This is the number of blocks per track on all tracks except track 0 pd_t0b Blocks Track 0 This is the number of blocks per track for track 0 This may be different than pd_b1k depending on the specific disk format Table 13 8 RBF Path Descriptor Options Table Structure continued Name Description pd_sas pd_ilv pd_toffs pd_boffs pd_trys pd_bsize Segment Allocation Size This value specifies the default minimum number of sectors to be allocated when a file is expanded Sector Interleave Factor Sectors are arranged on a disk in a certain sequential order 1 2 3 etc 1 3 5 etc The interleave factor determines the arrangement For example if the interleave factor is 2 the sectors would be arranged by 2 s 1 3 5 etc starting at the base sector refer to pd_sof fs Track Base Offset This is the offset to the first accessible track number Because Track 0 is often a different density Track 0 is sometimes not used as the
119. e disk boot routine to find the boot file and initiate the transfer 3 fdman then calls back the disk boot routines to accomplish the transfer of specific blocks of data from the disk If the device is a SCSI device 1 The disk boot data transfer routines call the services of a target independent scsiman module to manage the SCSI command protocol 2 scsiman uses the services of a target specific low level host adapter module to manage the transfer across the SCSI bus If you require a SCSI boot implementation on your target you need to create a host adapter module specific to your target using the example modules as prototypes Since the boot system can pass both configured and user parameters to booters a parser module is provided to process the argument lists and place the values in parameter structures accessible from the C language The parser fdman scsiman and the host adapter modules are implemented as pseudo booters During module startup they build up a standard boot device record bootdev with null service pointers and install it onto the list of available booters Instead of using the bt_data field to point to module globals it points to a pseudo booter specific record structure holding pointers to the pseudo booter s services and any applicable data The services of fdman and scsiman and those required of any SCSI host adapter are listed in the following sections KX MICROWARE The Boot Device bootdev R
120. e information about device drivers RBF supports a wide range of devices having different performance and storage capacities Consequently it is highly parameter driven The physical parameters it uses are stored on the media itself On disk systems this information is written on the first sector of track number 0 The device drivers also use the physical parameters stored on sector 0 These parameters are written by the format program that initializes and tests the media KX MICROWARE Understanding SCSI Device Driver Differences This section explains some unique aspects of SCSI device drivers The basic premise of the SCSI system is to break the OS 9 driver into separate high level and low level areas of functionality This enables different file managers and drivers to talk to their respective devices on the SCSI bus The device driver handles the high level functionality The device driver is the module called directly by the appropriate file manager Device drivers deal with all target controller specific device class issues for example SCSI hard disks or tapes Hardware Configurations Step 1 Step 2 The high level drivers Prepare the command packets for the SCSI target device Pass this packet to the low level subroutine module The low level subroutine module passes the command packet and data if necessary to the target device on the SCSI bus The low level code does not concern itself with the con
121. e interrupt level associated with the timer should be as high as possible A high interrupt level prevents ticks from being delayed and or lost due to interrupt activity from other peripherals Lost ticks cause the kernel s time keeping functions to lose track of real time This can cause a variety of problems in processes requiring precise time scheduling The interrupt service routine associated with the timer should be able to determine the source of the interrupt and service the request as quickly as possible Figure 11 1 Ticker Setup Directories and Files BOOTS INIT SYSMODS default des EXAMPLES r optional SYSTEMS IRQS RTC TICKER TESTBOOT EMBEDDED lt others gt PORTBOOT optional config des where applicable Ticker Support The tick functions for various hardware timers are in the TICKER directory There are two ticker routines e Tick initialization entry routine This routine is called by the kernel and enables the timer to produce interrupts at the desired rate e Tick interrupt service routine This routine services the tick timer interrupt and calls the kernel s clock service routine Note The ticker module name is user defined and should be included in the init module XX micRoware OS 9 Tick Time Setup You can set the tick timer rate to suit the requirements of the target system You should define the following variables Ti
122. e parts are contained in the following structure This structure is defined in rbf h typedef struct rbf_desc dd_com dd_descom rbf_path_opts dd_pathopt rbf_desc Rbf_desc Table 13 4 RBF Device Descriptor Structure Name Description dd_descom This is the common information structure IOMAN requires to be in all device descriptors dd_pathopt This structure contains the RBF path descriptor options and information IOMAN uses to initialize the device RBF copies this information into the path descriptor when a file is opened or created XX microware Logical Unit Static Storage Initialization IOMAN initializes logical unit static storage from the device descriptor using a declaration of the following structure This structure is defined in rbf h typedef struct rbf_lu_stat rbf_drv_info u_char rbf_lu_opts u_int32 rbf_lu_stat v_driveinfo the drive s information v_vector the interrupt vector v_irglevel the interrupt level v_priority the interrupt priority v_unused unused byte v_luopt logical unit options v_reserved 2 reserved Table 13 5 RBF Logical Unit Static Storage Structure Name Description v_driveinfo v_vector v_irgqlevel v_priority Disk Drive Information RBF maintains information about the media in use in this field A full description of this structure follows this discussion Interrupt Vector This is the vect
123. e to the system Edit the makefile file in lt Target gt ROM Add your timer directory name to the list of directory names used to define the TRGTS macro Step 3 Add the timer module name into the coreboot m1 file in lt Target gt BOOTS SYSTEMS PORTBOOT By doing this you ensure your timer module is rebuilt along with the bootstrap code and the rest of the low level system modules when e lt Target gt ROM makefile is invoked and included in the rom file e lt Target gt BOOTS SYSTEMS PORTBOOT makefile is invoked creating the boot image coreboot 6 Creating a Low Level Timer Module KX MICROWARE 116 OS 9 Porting Guide Chapter 7 Creating an Init Module This chapter includes the following topics Creating an init Module Init Macros WX MICROWARE 117 KX MICROWARE Creating an init Module Init modules are non executable modules of type MT_SYSTEM An init module contains a table of system start up parameters During start up init specifies the initial table sizes and system device names but init is always available to determine system limits It must be in memory when the system is booting and usually resides in the sysboot file or in ROM An init module begins with a standard module header The module header s m_exec offset is a pointer to the system s constant table The fields of this table are shown here and defined in the init h header file Within the INIT default des file i
124. ecord and Services Each booter module establishes one or more boot device records on the list of available boot devices in the Boot Services boot_svcs record The definition of the boot dev record appears in the header file MWOS SRC DEFS ROM rom h and appears here for illustration typedef struct bootdev bootdev Bootdev struct bootdev idver void infoid bt_addr the port address check for device existence u_int32 bt_probe Bootdev bdev Rominfo rinf initialize boot device bt_init Bootdev bdev Rominfo rinf read data from boot device bt_read u_int32 blks u_int32 blkaddr u_char buff Bootdev bdev Rominfo rinf write data from boot device bt_write u_int32 blks u_int32 blkaddr u_char buff Bootdev bdev Rominfo rinf terminate the boot device bt_term Bootdev bdev Rominfo rinf bring boot in from device bt_boot Bootdev bdev Rominfo rinf u_int32 bt_flags misc flags u_char bt_abname abreviated name bt_name full name and description void bt_dataj special data for boot device Bootdev bt_next next device in the list Bootdev bt_subdev sub device record u_char user_params user parameter array u_char config_params configuration parameter array u_char config_string configuration parameter string u_int32 autoboot_delay autoboot delay time u_int32 bt
125. ed by the exception handler then the handler must save the content of those registers prior to modification However the format of the short stack cannot be modified 5 This register contains the vector number of the exception that just occurred It is passed as a parameter to the exception handler which may be useful to the handler lr The link register is used by the exception handlers to dispatch to the target C code exception handler The C code handler is called using the b1r1 instruction so the link register is updated with the return address to the vector exception handler The C code handler then saves the current link register value on the stack in the eight byte location allocated by the vector code The return code of the handler restores the link register and returns to the vector code Wwf Note The C compiler by default generates code to save registers r14 r31 if the code generated uses any of the registers KX MICROWARE Initialization The vectors are initialized twice during the full booting sequence The first initialization occurs during the low level or bootstrap booting process The OS 9 low level boot code initializes the vectors so it can catch any exceptions that may occur during this portion of the booting sequence The second and final initialization occurs during the high level or kernel s boot stage Here the kernel links to the vectors module and calls its execution offset entry
126. er arming service 113 code example 106 de initialize service 110 directory diagram 107 get time service 111 initialize service 112 low level building 114 defined 106 required for autobooter with delay 106 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z low level network protocol booting 106 low level user state Hawk 106 scllio in interrupt mode 106 services record 108 starting up the low level system 114 timer_deinit de initialize timer service 110 timer_get get time service 111 timer_init initialize timer service 112 timer_set arm timer service 113 TOTCYLS 266 track base offset pd_toffs 255 track cylinder current v_trak 248 transfer size maximum pd _xfersize 257 TRKOFFS 264 try number of times pd trys 255 TRYS 265 UPC_LOCK SCF macro defined 193 use debug 314 usedebug module 314 user buffer base address pd_ubuf 174 v_0 246 v_attached 147 ABCDEFGHIJKLMNOPQRSTUVW XYZ v_baud 171 v_bkzero 248 v_blks_list 250 v_blks_rsrc_Ik 250 v_busy 164 SCF 159 v_cache 248 v_class 169 v_crsrc_lk 248 v_dcdoff 164 SCF array 159 v_dcdon 164 SCF array 159 v_dcdstate 172 v_dev_entry 146 v_diskid 247 v_dopts 249 v_driveinfo 244 v_endflag 249 v_entxirq 146 v_err 169 v_fd_free list 250 v_fd_free_rsrc_lk 249 v_file_rsrc_Ik 246 v_filehnd 246 v_free 247 v_free_rsrc_Ik 247 v_freesearch 247 v_getstat 146 v_hangup 161 SCF 159 v_harderr 248 v_inbufad 165 SCF 159 v_incount 165 SCFf 159 v_inempty 166 SCF 159 v_inen
127. er defining the system maximum age See the OS 9 Technical Manual for an explanation of priority Default value is 0 define MAXAGE 0 Table 7 2 Init Module Optional Macros with Default Values continued Name Description and Example EVENTS A number specifying the initial event table size Must be divisible by 8 Default value is 32 define EVENTS 32 COMPAT The compat word contains bit flags that are configuration parameters for the operating system Default value is 0x50 The init h file defines the flags that can be used B_GHOST Do not retain ghost sticky modules if set B_WIPEMEM Patternize allocated returned memory if set B_NOCLOCK Do not automatically set system clock B_EXPTBL Do not automatically expand system tables define COMPAT B WIPEMEM B_ GHOST WX microware Table 7 2 Init Module Optional Macros with Default Values continued Name Description and Example EXTENSIONS PREIOS SYS_T TOMAN_NAME MAX_SI ME ZONE GS A character string containing the names of OS 9 extension modules executed as the system is booting and after the OS 9 I O system has been initialized These modules do not need to be present in the boot file but are executed if present OS 9 system modules provided are cache Provides cache enabling and flushing fpu Provides software floating point math if necessary ssm Provides memory protection define EXTENSIONS O
128. er of recoverable errors that have occurred on the drive and media Only the driver uses this field RBF never accesses this field v_harderr Non Recoverable Error Count This is the number of non recoverable errors that have occurred on the drive and media Only the driver uses this field RBF never accesses this field v_cache Data Cache Pointer This field points to the data caching structure if caching is being used on the drive v_crsrc_lk Cache Data Lock Descriptor Lock descriptor structure for locking the disk cache data structure Table 13 6 RBF Drive Information Structure continued Name Description v_numpaths v_zerord v_init v_dopts v_endflag v_fd_free_rsrc_lk Open Paths On Device This is the number of open paths on the device Block 0 Read Flag RBF drivers use this flag to determine whether or not there is a valid sector 0 buffered RBF never accesses this field Initialized Drive Flag This flag indicates that the device has been initialized RBF drivers use this field to prevent themselves from initializing a device more than once Copy of Path Descriptor Options This is a copy of the path descriptor options These are detailed in the following section Byte Ordering Flag This flag indicates the byte ordering used by the processor BIG_END Processor uses most significant byte first order LITTLE_END Processor uses least significant byte first order
129. ers conn_entry is not used in the drivers but it is present because the protocols also use the same prototypes This entry point is called by hlproto to turn on off the interrupts It is also called by the notification handler routine desten is the destination address XX micRoware arptbl_update Update ARP Table Syntax error_code arptbl_update Proto_srvr PSIVI LIMbuf mb Eth_header eth Description The ARP table update function is called from the driver s proto_read and proto_upcall routines It performs ARP table updates if the sender included this service s Ethernet address through this service s gratuitous ARP or other means and did not make an ARP request This prevents this service from having to make ARP requests This service compares this address to its own address to determine if the packet was directed to it In addition packets that are not directed to this service are filtered by returning ERROR preventing the service from searching the stack in the interrupt context Parameters psrvr points to the proto_srvr structure mb points to the packet received eth points to the Ethernet address of the packet received arpwhohas ARP Packet Request For Hardware Address Syntax error_code arpwhohas Proto_srvr psrvr struct in_addr addr Rominfo rinf Description arpwhohas broadcasts an ARP packet and asks for the hardware address of the machine with the su
130. est to the device s driver SCF Logical Unit Static Storage This section describes the definitions of the logical unit device static storage area for SCF type devices The structure definition of the device static storage is found in scf h IOMAN copies the initial values from the device descriptor module into the logical unit static storage when a path to the device is opened This structure contains the important variables used by the device driver and SCF to communicate and transfer data Device Static Storage Structure Definition Example typedef struct scf_lu_stat hardware_vector v_vector IRQ vector number u_char v_irglevel IRQ interrupt level v_priority IRQ polling priority v_pollin polled input flag 1 polled O IRQ driven v_pollout polled output flag l polled O IRQ driven v_inhalt input halted flag v_hangup set non 0 when data carrier is lost v_outhalt output IRQ s disabled when non zero u_int16 v_lu_num logical unit number v_wait indicates process is waiting on I O u_int32 v_irqmask Interrupt mask word v_savirg_fm previous interrupt mask word SCF only v_savirq_dv prev interrupt mask word driver only v_savirg_ll reserved for future use process_id v_wake ID of process waiting I O operation v_busy ID of process currently using device v_lproc of the last process to use this unit v_sigproc 3
131. eters bdev points to the disk booter s boot dev record Pink points to the rominfo structure XX micRoware bt_probe Probe Verify Device Syntax u_int32 bt_probe Bootdev bdev Rominfo rink gt Description The boot system calls bt_probe to determine if the device is available Usually this routine at least confirms a boot area can be returned back to the boot system Devices with fixed configuration can also be probed to determine if they exist Devices that can be reconfigured by the user probably cannot determine this at this time since the return value is used when presenting the boot menu to determine if the device should be marked as available SCSI device booters are likely to determine if the scsiman module is available as part of the probe Parameters bdev points to the disk booter s bootdev record rinf points to the rominfo structure bt_read Read Data From Device Syntax u_int32 bt_read u_int32 blks u_int32 blkaddr u_char xp ff Bootdev bdev Rominfo rinf Description This routine causes block reads to occur For disk booters it is likely to be called from fdman or scsiman routines Otherwise it would be called from the booter s own bt_boot routine Parameters blks is the number of blocks to read blkaddr is the address of the block on the media buff points to the buffer in which to store the data bdev points to the disk booter s boot dev record rin
132. f the communications port for user state connections Operation WX microware Verify configuration of low level timer enable receive interrupts on port CONS_SETSTAT_ROMBUG_OFF Indication Operation Issued indirectly through notification services when the RomBug debug client returns control from any breakpoint exception or d_sysdebug entry Restore any applicable port or chip specific configuration including interrupts CONS_SETSTAT_ROMBUG_ON Indication Operation Issued indirectly through notification services when the RomBug debug client gets control on any breakpoint exception or d_sysdebug entry Save any applicable port or chip specific configuration including interrupts Disable any receive interrupts on port CONS_SETSTAT_RXFLOW_OFF Indication Operation Issued when a driver user Such as 11slip needs to restrict the flow of received data If hardware handshaking is configured assert hardware flow control on otherwise if software handshaking is configured send an X OFF CONS_SETSTAT_RXFLOW_ON Indication Issued when a driver user Such as 11slip needs to restore the flow of received data Operation If hardware handshaking is configured turn off hardware flow control otherwise if software handshaking is configured send an X ON WX microware cons_term De initialize Port Syntax u_int32 cons_term Rominfo rinf Consdev cdev Descripti
133. f all of the volatile registers will be destroyed by the C code handlers Because of these conventions the vector exception handlers are not coded to maximize efficiency but rather to maintain the integrity of the process context state If for some reason a dedicated application requires a decrease in exception latency from what the standard exception handlers provide it is possible to modify the vector exception handlers and the C code handlers to achieve these requirements The Ultra C C compiler is capable of generating code using a callee register save subroutine calling convention In this case the code is generated to preserve the contents of any of the registers it expects to destroy This allows the C code exception handlers to be compiled to preserve the content of the registers it uses making it possible to reduce the burden of context saving required by the vector exception handler The vector exception handler can be written to use a bare minimum of registers to dispatch to the C code handler thus reducing its context save operation to only the set of registers it modifies in getting to the C code handler While this makes it possible to reduce the latency in servicing an exception this callee save convention is not more efficient in the case where many C code handlers reside on the same vector and have to be polled to locate the target handler In this case each of the C code handlers being compiled for the callee save mode
134. f points to the rominfo structure WX microware bt_term De initialize Device Syntax u_int32 bt_term Bootdev bdev Rominfo Fink gt Description This routine deinitializes the device as necessary Parameters bdev points to the disk booter s bootdev record rink points to the rominfo structure bt_write Write Data To Device Syntax u_int32 bt_write u_int32 u_int32 u_char Bootdev Rominfo Description blks blkaddr Hurt bdev rinf This optional routine causes block writes to occur Currently it is never called but the service was defined in case some custom low level utility required the function of a custom booter As with the low level serial and timer modules the booter modules are started ata p2start entry point This entry is responsible for building the necessary bootdev records and installing them on the list of available booters Remember the portmenu module services discussed earlier are still required to configure the appropriate booters for autobooting or menu presentation Parameters blks blkaddr buff bdev rinf is the number of blocks to read is the address of the block on the media points to the buffer in which to store the data points to the disk booter s bootdev record points to the rominfo structure L mm 4 f l 7d Creating Booters KX MICROWARE The parser Module Services ine O Access
135. get platform specific since the target determines the I O location of the PIC and mapping of interrupt numbers to vectors is established by the port to the target The third type of library is a subroutine module that can be accessed through a helper library linked with the driver This enables drivers to be distributed in object form with plug in cards for bus based systems and remain portable across target platforms with possibly differing interrupt controllers or mappings The example picsub module is built from a special root psect and the piclib 1 library mentioned above The example helper libraries are picsub il and picsub 1 for both l code and traditional linking methods For CPU boards that do not employ an interrupt controller the distribution provides the nopiclib il and nopiclib 1 libraries and the nopicsub subroutine modules These libraries do nothing but return a SUCCESS status The services available to drivers and the services to be provided by other custom PIC libraries are __pic_enable and _pic_disable a piclib Functions VJ Table C 1 PIC Services Function Description _pic_disable Disable interrupt on PIC hardware _pic_enable Enable interrupt on PIC hardware For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions OS 9 Porting Guide WX microware _pic_disable Disable Interrupt On PIC
136. gnized By Example Booter Modules Keyword Description Port Address of Interface port Address of interface coded as 0xFF00 lt bus gt lt device unit gt for autoconfigured PCI devices si Starting partition index number ei Ending partition index number device Name of low level SCSI host adaptor module reset SCSI reset flag aux_device Name of secondary interface WX microware Table 14 6 Standard Configuration Parameters Recognized By Example Booter Modules continued Keyword Description Port Address of Interface aux_port Address of secondary interface debug Debugging flags for SCSI booters bit values are SCSTI_DEBUG_CMD 1 SCSI_DEBUG_DATIN 2 SCSI_DEBUG_DATOUT 4 SCSI_DEBUG_MSGIN 8 SCSI_DEBUG_MSGOUT 0x10 SCSI_DEBUG_STATUS 0x20 SCSI_DEBUG_INFO 0x40 When SCSI debug options are employed it is recommended that the SCST_DEBUG_INFO option be used This displays useful information as debug information is processed Debug phases are displayed in the following form Data Out Phase Data IN Phase Command Phase When the SCSI_DEBUG_INFO flag is used the following message is display at the start of each SCSI command SCSI Debug Enabled DO DI CM Drive ID 0 J ll Appendix A The Core ROM Services The modularity of the boot code is accomplished by group
137. h low level ROM and high level OS drivers Building the Low Level Serial I O Modules The makefile for your I O module should be created in a properly named subdirectory of your ports ROM directory for example lt Target gt ROM 10O lt nnnn gt Use the makefiles from the example ports as a guide Figure 4 2 Low Level Serial I O Source Code Directories for Building a Module OS9000 makefile TN SYSTEM lO lt nnnn gt TN config des where applicable Step 1 Step 2 Step 3 KX MICROWARE To add your low level serial I O module to the system Edit the makefile lt Target gt ROM makefile Add your device directory name to the list of targets used to define the TRGTS macro Add the low level serial I O module name into the corboot m1 file in the PORTBOOT directory By doing this your low level I O module is rebuilt along with the bootstrap code and the rest of the low level system modules when e lt Target gt ROM makefile is invoked and included in the ron file e and lt Target gt BOOTS SYSTEMS PORTBOOT makefile is invoked creating the boot image coreboot The Console Device Record A console device consdev record is maintained for each low level serial I O device included with the low level system modules This record is used to access the services of the I O module and to maintain lists of such devices The definition of consdev appea
138. high level handler The vector code associated with the system call vector functions similar to the general exception vector code except the system call vector code does not change the value of r3 as stated in the r3 definition in this section prior to calling the high level exception handler The following list describes the important register usage in the handlers sprg0 Prior to the exception the sprg0 register contains a pointer to the kernel s global static storage area The software IRQ stack is located just below the kernel s globals sprgl Prior to the exception the sprg1 register contains a pointer to the top of the current processes system state stack sprg2 This register is used by both categories of handlers as a temporary register for preserving the state of the current process condition codes register sprg3 This register is also used by both categories of handlers as a temporary register for saving the current stack pointer rl Upon calling the high level C code exception handler r1 contains the stack pointer for use for the duration of the exception handling It is also pre decremented by eight bytes to account for the stack space required by the C code handler to save the content of the link register and the current value of the stack pointer The Ultra C C compiler normally allocates these eight bytes for subroutine calls KX MICROWARE Note The OS 9 operating system assumes the r1 register poin
139. ices record Table B 8 Console Services Function Description rom_getc Read the first character rom_getchar Read the first character from the system console WX MICROWARE Table B 8 Console Services continued Function Description rom_gets Read a null terminated string from the system console rom putet Output one character rom_putchar Output a character to the system console rom_puterr Write error code to the system console rom_puts Write a null terminated string to the system console For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions rom_getc Read the First Character Syntax char rom_getc Rominfo rinf Consdev cdev Description rom_getc calls the low level read routine of the specified console device record to read a single input character from the associated console device rom_getc returns the character read Parameters rinf points to the rominfo structure cdev points to the console device record for the console device to be used Example char ch ch rinf gt cons gt rom_getc rinf cdev WX microware rom_getchar Read First Character From the System Console Syntax char rom_getchar Rominfo rinf Description rom_getchar Calls the low level read routine of the console device record configured for use as the system consol
140. ies contain examples of these files that you can use as a guide Table 3 1 Bootstrap Code Files You Need to Create File Name Content Summary systype h Target system hardware dependent definitions rom_cnfg h The bootstrap memory list and stack definitions ROM console and boot device record definitions and the ROM memory lists sysinit c Target specific hardware initialization your system may require following a system reset A WARNING Do not modify the other bootstrap source code files If you alter these files the port code may not function correctly The rom_cnfg h File The rom_cnfg h header file contains the target system definitions only used for the bootstrap code This includes patchable memory locations containing the following information e Top of the bootstrap stack e Size of memory reserved for low level system modules e Bootstrap memory lists XX microware For More Information Some processors may require additional steps See your Getting Started With OS 9 for lt target gt for your processor specific porting information Bootstrap Stack Top and Boot Module Memory The bootstrap code allocates memory from the first RAM memory segment of the system into three parts as shown in Figure 3 1 lt MWOS gt 0S9000 Bootstrap Source Code Directories The bootstrap code allocates the global data area and the stack area for its own use It reserves the special memory pool for the low leve
141. ile to build your low level system modules This makefile forces a make within each of the subdirectories included in its TRGTS macro to build the low level system modules Use the makefile lt Target gt BOOTS SYSTEMS PORTBOOT makefile to build your boot image This makefile not only creates the rom file but also oversees the creation of the boot image called coreboot Or os9kboot Note You may get errors when running make If these problems are not related to low level system modules you can ignore the errors This is because you only need the coreboot file for testing and it is created before the make exits with errors while trying to build the rom file 3 Porting the Boot Code WX MICROWARE 56 OS 9 Porting Guide Chapter 4 Creating Low Level Serial I O Modules This chapter includes the following topics Creating the Low Level Serial I O Modules The Console Device Record Low Level Serial I O Module Services Starting up the Low Level Serial I O Module o N AA MICROWARE WX MICROWARE Creating the Low Level Serial I O Modules While it is not absolutely necessary to have a serial I O console device on your system it is strongly recommended that your initial port include both a console device and an auxiliary serial I O communications device The console I O routines are used by the bootstrap code and low level system modules for error messages and by the debugger and menu booters for inte
142. ime clock code is executed to read the current time from the device If the time read from the real time clock is valid no errors occur and system time slicing and time keeping functions correctly You do not need to set the system time If the time read from the real time clock is not valid the real time clock code returns an error This can occur if the battery back up malfunctions The system time is invalid but time slicing occurs You can correctly set the real time once the system is up The system does not have a fully functional debugged tick timer module and or real time clock module In this situation executing the tick and or real time clock code has unknown and potentially fatal effects on the system To debug the modules prevent the kernel from performing an __os_setime call during coldstart by setting the B_NOCLOCK flag in the init module s m_compat word This enables the system to come up without the clock running Once the system is up you can debug the clock modules as required Debugging Disk Based Clock Modules Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 Step 1 Step 2 Step 3 You should not include any clock modules in the bootfile until they are completely debugged Use the following steps to debug the clock modules Make the init module with the B_NOCLOCK flag in the m_compat byte set Exclude the modules to be tested from the boottfile Bring up the system Load
143. info structure specifies the priority of execution relative to the other registered handlers Lower numbers are executed prior to higher numbers when transitioning from the operating system to the ROM When transitioning back the handlers are executed in the opposite order points to the actual handler being registered Its parameters are the transition direction and a local parameter pointer specifies the parameter value to be passed to the handler on its activation This typically points to a data structure defined by the handler specifies the address where the handler identification is to be returned B Optional ROM Services WX MIC ROWARE 358 OS 9 Porting Guide Appendix C piclib Functions WX MICROWARE 359 KX MICROWARE Overview The functions to enable and disable interrupts on programmable interrupt controllers PICs have been externalized into libraries to minimize the platform dependency on driver sources and binaries There are three types of libraries available for different driver requirements Examples of them for 8259 like PC PICs are supplied in your OS 9 Embedded release The first two types of libraries are for drivers that are to be optimized for a particular target platform The example libraries are piclib il for l code linking and inlined code optimization and piclib 1 for linking with driver relocatable assembler output files during debugging These libraries are built to be tar
144. ing the services into subsets and providing access to these subsets through record structures This appendix describes the core structures and their services for all target systems Also the library services available to all modules is included This appendix contains the following topics The rominfo Structure Hardware Configuration Structure Memory Services ROM Services Module Services p2lib Utility Functions WX MICROWARE KX MICROWARE The rominfo Structure The rominfo structure is the focal point of all modularized boot code services It consists of pointers to all the sub structures organized by type of service provided The definition of the rominfo structure resides in the include file MWOS SRC DEFS ROM rom h and appears here simplified for illustration typedef struct rominfo idver infoid id_version for rominfo Hw_config hardware hardware config struct ptr Mem_svcs memory memory services struct ptr Rom_svcs rom rom services struct ptr Mod_svcs modules module services struct ptr Tim_svcs timer timer services struct ptr Cons_svcs cons console services struct ptr Proto_man protoman protocol manager struct ptr Dbg_svcs dbg debugger services struct ptr Boot_svcs boots boot services struct ptr Os_svcs Os OS services struct ptr Cnfg_svcs config configuration services struct ptr Notify_svcs notify notification service
145. ing this section DEV_SPECIFICS Device Specific Variable MACRO This is a C language macro The author of a device driver can expand this macro to include additional variables in the logical unit static storage structure The additional field can be defined in a header file for the device driver being written The fields are included in the structure when the device descriptor for the logical unit is created SCF Logical Unit Static Storage Options This section describes the definitions of the device options logical unit options for SCF type devices The structure definition of the device options is shown here This structure is defined in scf h IOMAN copies the device options from the device descriptor module into the logical unit static storage when a path to the device is attached The device options may be changed afterwards using the SS_LUOPT function of I_GETSTAT and I_SETSTAT service requests or from the keyboard using the xmode utility typedef struct u_int16 u_char scf_lu_opts v_opt size size of logical unit options section v_class device type 0 SCF v_err accumulated errors v_pause immediate pause request v_line lines left until end of page v_intr keyboard interrupt character v_quit keyboard quit character v_psch keyboard pause character v_xon X ON character v_xoff X OFF character v_baud baud rate v_parity
146. ints to the device entry INIT Initialize Device Hardware Syntax error_code init Dev_list device_entry Description The INIT routine must 1 Install driver interrupt service routine s on the system interrupt polling table using the F_IROQ service request 2 Initialize the device control registers with the functionality specified by the logical unit options section 3 Output a null byte to get the transmitter interrupts activated The transmitter interrupts should not actually be enabled until later when SCF has data to output and calls the driver s enable transmitter interrupts routine Parameters device_entry is the device list entry for the device XX micRoware IRQ SERVICE ROUTINE Service Device Interrupts Syntax error_code input_irg Dev_list device_entry error_code output_irg Dev_list device_entry Description Although the interrupt service routine s is not included in the driver s entry point table and not called directly by SCF it is an important routine in interrupt driven device drivers It functions as follows 1 Query the device to determine if the device caused the interrupt If the device did not cause the interrupt exit immediately with an EOS_NOTME error Service the device interrupt receive transmit data This routine puts its data into or get its data from the buffers defined in the logical unit static storage Wake up any process waiting for
147. ions 261 path descriptor options table 252 RBF macro block interleave factor 263 block offset 264 block size 264 blocks per track 263 blocks per trackO 263 cylinders on drive 266 device type 261 DMA transfer mode 263 driver format 262 first cylinder for reduced write current 266 first cylinder for write precompensation 265 format control flags 265 logical block offset 266 minimum segment allocation 263 name of driver 267 number of cylinders 262 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z number of heads or sides 261 number of retries before error 265 park cylinder 266 SCSI controller ID 267 SCSI logical unit number 265 step rate 261 track offset 264 write verification flag 261 RBF reserved lu_reserved 252 v_reserved 245 250 rbf h defined 243 RBSCCS 226 RBTEAC 226 READ 237 SCF 154 read character from input port 73 read data from device bt_read 277 read sectors READ 237 read_bootfile 286 readsccs 294 real time clock support 215 reduced write current cylinder pd_rwr 256 REDWRITE 266 reg_hndlir 357 register usage for Power PC vector code 129 request to send flag SCF macro defined 197 resource list lock descriptor v_free_rsrc_lk 247 resource lock ID v_lockid 167 rewind _tape 295 rinf gt cons 345 ROM memory list 45 ABCDEFGHtIJKLMNOPQRSTUVW XYZ rom_config h 43 rom_findmle 318 rom_findmod 319 rom_free 309 rom_getc 347 rom_getchar 348 rom_gets 349 rom_hellomsg field 314 rom_malloc
148. ions for the proto_srvr Structure and a list of the entry point services Add the driver to your boot code Remake the boot code Test communications using the Ethernet driver you created Required Ethernet Driver Functions The following sections define the required functions for implementing a low level Ethernet driver Proto_srvr Structure This structure defined in rom h is common to all protocols and drivers and identifies the modules in the low level protoman protocol list struct proto_srvr idver infoid id version for proto_srvr if defined NEWINFO Proto_srvr next next protocol stack in list u_int32 proto_type_id protocol id error_code proto_install Rominfo u_char Installation proto_iconn Llpm_conn u_int32 initiate conn proto_read Llpm_conn u_int32 L1Mbuf read conn proto_write Llpm_conn u_int32 write conn proto_status Llpm_conn u_int32 void get status proto_tconn Llpm_conn u_int32 terminate conn proto_deinstall Rominfo pro pro De installation to_timeout Rominfo Proto_srvr timeout processing to_upcall Rominfo Proto_srvr void LL ISR upeall void proto_data server local data structure ptr u_int32 proto_data_size protocol s data area size proto_conn_cnt number of active connections Consdev proto_cons_drvr
149. ister usage 129 services 128 VERIFY 261 virtual console driver 204 waiting for I O V_wait SCF 159 waiting process ID v_wake 163 WORDSIZE SCF macro defined 197 WRITE 241 SCF 157 ABCDEFGHtIJKLMNOPQRSTUVWX YZ write character to output port cons_write 73 write data to device bt_write 279 write precompensation cylinder pd_wpc 256 write sectors WRITE 241 write verification pd_vfy 253 X OFF SCF macro defined 193 X OFF character v_xoff 171 X OFF function SCF macro defined 193 X ON SCF macro defined 193 X ON character v_xon 170 X ON function SCF macro defined 193 OS 9 Technical Manual Product Discrepancy Report To Microware Customer Support FAX 515 224 1352 From Company Phone Fax Email Product Name Description of Problem Host Platform Target Platform
150. ite routine for drivers that have interrupt driven output returns without error The write routine for drivers with polled output performs the same functions as an output interrupt service routine except it polls the hardware to transmit the next character Parameters path_desc points to the path descriptor device_entry points to the device entry KX MICROWARE Using SCF Device Descriptor Modules The SCF device descriptor consists of four parts e The OS 9 module header e The common information required by IOMAN for all descriptors e The path descriptor options e The logical unit static storage Along with the common IOMAN information the scf_desc structure contains the offset for the name of an output device to be used if different from the input device SCF examines this structure when processing an OPEN request This structure is defined in scf h typedef struct scf_desc dd_com dd_descom common device descriptor variables u_int32 dd_outdev alternate output device name offset u_int16 dd_rsvd_scf 2 reserved space scf_desc Table 9 3 SCF Device Descriptors Name Description dd_descom This is the common information structure IOMAN requires be in all device descriptors dd_outdev This is the offset to the name of the output device to be used instead of the input device If this field is non zero SCF attaches to this device initializes it and issues an SS_OPEN setstat requ
151. iver can simply poll the device waiting for command completion but this hampers time sharing performance If the disk controller cannot be interrupt driven it is necessary to perform a programmed O transfer KX MICROWARE wmf Note Whenever logical sector zero is read the idblock section must be copied to the drive table of logical unit static storage If bit number 1 in the pd_cnt1 field is clear RBF only requests one sector reads If the bit is set RBF may request up to pd_xfersize bytes of data to be read RBF divides pd_xfersize by the block size to determine the maximum number of blocks that can be transferred pd_xfersize is defined in the path descriptor options section of the device descriptor Parameters blks is the number of blocks to transfer blkaddr is the starting block address pd is the path descriptor dev points to the device list entry SETSTAT Set Device Status Syntax error_code setstat void pb Rbfpd pd Dev_list dev Description These routines are wildcard calls used to get the device s operating parameters as specified for the OS 9 set stat service requests Typical RBF drivers have routines to handle the SS_WTRK and SS_RESET setstat calls Usually all getstat calls and other setstat calls return with an EOS_UNKSvc UnKnown Service Request error Parameters pb is the status parameter block pd is the path descriptor dev is the device list entry TERMIN
152. l cross hosted make command sequence chd SCF SC68901 DESC S os9make The makefile invokes the EditMod utility to create the descriptor EditMod generates device descriptors from description files For More Information The information in this chapter describes how EditMod can be used to create device descriptors EditMod can also list or edit the contents of a device descriptor For more information about this utility refer to the Utilities Reference and OS 9 Device Descriptor and Configuration Module Reference manuals SCF Device Descriptor Macros Refer to the OS 9 Device Descriptor and Configuration Module Reference for a complete discussion of the fields in the SCF configuration files Table 9 10 on page 188 and Table 9 11 on page 190 contain the SCF macro definitions used for creating SCF device WX micRoware descriptors Each table gives the name of the field the name of the macro an explanation of the macro and an example definition in many cases this is the default value set by Microware These five macros are common to RBF SCF and SBF descriptors Table 9 10 RBF SCF and SBF Common Descriptors Name Description and Example PORTADDR VECTOR TROLEVEL Controller Address This is the address of the device on the bus Generally this is the lowest address that the device has mapped Port address is hardware dependent define PORTADDR Oxfffe4000 Interrupt Vector
153. l system modules to use The definitions for the size of the bootstrap stack area ROMStackSz and the boot module memory pool ResvMemSz are given in rom_cnfg h as shown in the following example _asm ROMStackSz equ 4000 KB ResvMemSz equ 20000 128KB romstack dc l _dsizet tResvMemSz ROMStackSz dc l1 ROMStackSz size of ROM stack The linker produces a link map for the romcore bootstrap image when it is built Using this map the offset of romstack can be found Once this address is known a 32 bit value at that address can be patched to change the size of the memory area reserved for low level system modules Additionally by patching in the proper 32 bit values at that address and the following address the size of the bootstrap stack area can be changed Figure 3 2 shows the memory diagram of this first RAM segment Figure 3 2 First RAM Memory Segment Allocated by the Bootstrap Code bootstrap global data q _dsize low level system module lt ResvMemSz reserved memory bootstrap stack ROMStackSz lt i initial Bootstrap Stack Top Bootstrap Memory Lists The ROM memory list is made of pairs of 32 bit integers specifying start and end boundaries for memory lists The first list is used to map the system s available RAM memory The second list is used to map special memory regions treated as ROM memory and searched in a non destructive fashion Special memory areas may include ROM flash or NVRAM memory
154. l system starting timer 114 ABCDEFGHIJKLMNOPQRSTUVW XYZ low level timer defined 106 LSNOFFS 266 lu_ctririd 251 lu_lun 251 lu_reserved 252 lu_stp 251 lu_tfm 251 lu_totcyls 252 LUN 260 SCF macro defined 189 LUPARITY SCF macro defined 196 m_exec init module offset 118 macro definitions RBF 261 macros SCF device descriptor 187 macros definitions init module 119 MAX_SIGS macro 124 MAXAGE macro 122 MAXBUFF SCF macro defined 190 maximum data for input buffer SCF macro defined 190 maximum data for path buffer v_maxbuff 165 mbuf find and initialize find_n_init_mbuf 93 mem_clear 311 mem_svcs 309 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z Micropolis 4221 hard disk 225 MINPTY macro 122 MODE SCF macro defined 190 module header 118 MPUCHIP macro 121 MT_DEVDRVR_ 231 MT_SYSTEM init module type 118 mubf initialize init_eth_mbuf 94 MVME147 CPU 226 MVME1603 225 MWOS master directory structure 12 next data input pointer to input buffer v_infill 166 next data input pointer to output buffer v_outfill 167 next data output pointer from input buffer v_inempty 166 next data output pointer from output buffer v_outempty 167 NINSIZE SCF macro defined 192 non standard definitions device specific macros 198 268 notification services callback handler 74 notification_handler handle callback 74 notify_svcs optional ROM services 354 nulls after end of line ABCDEFGHtIJKLMNOPQRSTUVW XYZ SCF macro defined 19
155. le rinf gt cons get the console services record pointer Consdev cdev local console device structure pointer verify that a console services module has been initialized if console NULL return EOS_NOCONS cannot install w o the console services record initialize device record for our device cdev amp cons_r point to our console device record cdev gt struct_id CONSDEVID id and version tags cdev gt struct_ver CDV_VER_MAX export our service routine entry points cdev gt cons_probe amp i016450_probe cdev gt cons_init amp 1016450_init WX MICROWARE amp 1016450_term amp 1016450_read cdev gt cons_write amp 1016450_write cdev gt cons_check amp 1016450_check cdev gt cons_term cdev gt cons_read The following services are not required for the initial port cdev gt cons_stat amp 1016450_stat cdev gt cons_irg amp 1i016450_irq a initialize the device configuration data cdev gt cons_addr void COMM2ADDR base address of I O port cdev gt cons_baudrate CONS_BAUDRATE_9600 communication baud rate cdev gt cons_vector COMMVECTOR interupt vector cdev gt cons_priority COMMPRIORITY interupt priority cdev gt poll_timeout 2000 polling routine timout value cdev gt cons_abname u_char COMM2ABNAME abreviated device name cdev gt cons_name u_char COMM2NAME
156. ler can transfer at one time The size is specified in bytes This parameter is format specific KX MICROWARE Building RBF Device Descriptors Step 1 Step 2 Making OS 9 device descriptors involves two steps Modify the appropriate C macro definitions within the RBF lt Driver gt config des for a specific device descriptor Make the descriptor using the associated makefile The config des file is organized so the macro definitions for a particular descriptor are grouped together For example the following section of config des contains the macros that must be defined this is macros that do not have pre defined defaults for the RBF ram descriptor They are grouped together within a C macro conditional KK KKK RR KR KR RK k k A KK RK KK ROKK ORK KK k k Ram Device Default Definitions All associated descriptors IA RA AR A IR RA AR I A I A A I Module header macros define MH_EDIT 0x7 Device descriptor common macros define PORTADDR 0 define DRVR_NAME ram define MODE UXETTE rbf macros define BLKSTRK 2048 multiplied by system wide BLKSIZE default of 256 will equal 512 KByte ram disk y EEKE K kkk kkk kkk kkk kkk kkk kkk kk k kk kkk k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k End of Ram Device Default Definitions Fe FR AA I A I A I AI IIIA AI III AI II III III AI III A IIE III A I Ik A AIC a 8K HI eR a A A A A I A
157. low with the notification services Parameters Tint points to the rominfo record structure cdev points to the console device record for the device XX micRoware cons_irq Polled Interrupt Service Routine for I O Device Syntax u_int32 cons irg Rominfo rini Consdev cdev Description cons_irq is an interrupt service routine installed for the device performing the following polling interrupt service on receipt of a device interrupt Step 1 Disables further interrupts on the device Step 2 Clears the interrupt from the device Step 3 Initializes the low level polling timer Step 4 Sets the polling time out value and loops through the process of checking the device and timer until either a character is received or the time out occurs Step 5 Sends a character that is received up the protocol stack by calling the uplink routine installed in the console device structure Step 6 Repeats steps 2 through 5 until a time out occurs Step 7 Re enables device interrupts and returns Parameters rinf points to the rominfo record structure cdev points to the console device record for the device cons_probe Probe For Port Syntax u_int32 cons_probe Rominfo rinf Consdev cdev Description cons_probe tests to see if the hardware described by the console device record cdev is present This could be a read of an I O register based on the value of cons_addr in the console device record
158. m ticker 17 step 12 more drivers and devices 18 step 13 floppydisk boots 18 step 2 copy EXAMPLE directory 15 step 3 copy bootstrap code 15 step 4 create low level serial driver 16 step 5 create Hawk driver 16 step 6 create low level timer 16 step 7 include Hawk support 17 step 8 create init module 17 step 9 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z PIC driver 17 step rate floppy disks lu_stp 251 stop bits SCF macro defined 196 stop bits number v_stopbits 172 STOPBITS SCF macro defined 196 struct_size 306 suffixes filename 13 summary of porting steps 15 swap_globals Ethernet driver services 81 swap _globals 336 SYS_ DEVICE macro 120 SYS_ PARAMS macro 120 SYS_ PRIOR macro 122 SYS_START macro 119 SYS_TIMEZONE macro 124 sysinit entry point 48 sysinit c 43 entry points 48 sysinit c file 48 sysinit1 C routine 49 sysinit2 C routine 49 systype h 43 systype h file 47 tab character pd _tabch 177 tab size pd_tabsiz 179 ABCDEFGHIJKLMNOPQRSTUVW XYZ TABSIZE SCF macro defined 195 tape initialize init_tape 291 rewind rewind _tape 295 target defined 10 interconnection with host 11 TERM RBF terminate routine 240 TERMINATE RBF 240 SCF 156 test disk driver 228 tick interrupt device 208 tick timer activation 211 OS 9 setup 210 TICK_NAME macro 119 ticker routines tick initialization entry routine 209 tick interrupt service routine 209 time out for O_READ READLN pd_ time 180 tim
159. mb points to the returned mbuf so it can be used WX microware init_eth_mbuf Initialize an mbuf Syntax void init_eth_mbuf Description The init_eth_mbuf function is called from proto_install to initialize an mbuf after allocating memory for the mbuf pool Low Level ARP The ARP included with the low level Ethernet driver has minimal functionality Low level Ethernet drivers do not avoid sent ARP requests Whenever a driver receives an ARP IP packet it saves the sender s hardware address if the packet is directed to this driver assuming the driver has sent a request since it wants to communicate with the driver The low level Ethernet driver processes the ARP request and replies to the sender The driver also updates an ARP table without removing any entries Table 5 3 Low Level ARP Functions Function Description arpinit arpinpu t arpresolve arptbl_update arpwhohas in _ arpinput Low level ARP init function ARP input processing routine Resolves hardware addresses Update ARP table ARP packet request for hardware address ARP input processing and replying function 5 Creating a Low Level Ethernet Driver KX MIC ROWARE For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions 96 OS 9 Porting Guide arpinit Low Level ARP init Function Syntax error_code
160. n 285 path buffer base address pd _pbuf 174 path buffer size v_pdbufsize 165 path buffer size for this device 159 path descriptor SCF type devices 173 path descriptor buffer size SCF macro defined 191 path descriptor list v_filehd 246 path descriptor option pointer v_pdopt 167 path descriptor options pd opt 175 path descriptor options size pd_optsize 176 path descriptor options table RBF 252 SCF 175 path descriptor options copy v_dopts 249 PATHS macro 122 pause flag v_pause 169 PCF booter support pcman 24 pcman booter support 24 pd_alf 178 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z pd_backsp 178 pd_bellch 177 pd_blk 254 pd_boffs 255 pd_bsize 255 pd_bspch 177 pd_ case 177 pd_cntl 256 pd_col 179 pd common 173 pd_curpos 174 pd cyl 254 pd_delete 178 pd_deventry 180 pd_echo 178 pd_echoflag 174 pd_endobuf 174 pd_eofch 176 pd_eorch 176 pd_err 179 pd_evl 174 pd_ format 254 pd_ilv 255 pd_inmap 176 pd_insm 179 pd_lost 175 pd_Isnoffs 257 pd_nulls 179 pd_opt 175 pd_optsize 176 pd_outdev 173 pd page 179 pd park 256 pd pause 178 pd pbuf 174 pd _pbufpos 174 pd_reqcnt 174 pd_rwr 256 pd sas 255 pd_ sid 253 pd t0b 254 ABCDEFGHIJKLMNOPQRSTUVW XYZ pd_tabch 177 pd_tabsiz 179 pd time 180 pd _toffs 255 pd trys 255 pd_ubuf 174 pd_vfy 253 pd_wpc 256 pd_xfersize 257 PIC disable interrupt 362 vectornumber 362 PIC enable interrupt 363 vectornumber 363 pointer to path descriptor options v_pdopt SCF 160 polled in
161. n and a RomBug prompt achieved scllio can be configured as the high level console to bring the system up to a shell prompt before a proper high level driver is completed scl1lio is also useful for initial testing of the polled interrupt mode of a low level driver Polled interrupt support is necessary if the low level driver is to be used to support Hawk communication This mode is also used by scl1lio when in interrupt driven mode This is a less complex use of the polled interrupt mode of the low level driver scllio can be used to test this mode without involving the various network layers of the TCP IP communications stack The low level device driver called by scllio is specified in the device descriptor used with scllio The device descriptor field v_llconsname points to a string containing the abbreviated name the cons_abname field of the console device record of the low level console you want scllio to communicate through Two special name strings consdev and commdev can be used in this field to specify respectively the configured system console device and communication port These allow generic specification of a high level console and communication port based strictly on low level configuration The reference platform in OS 9 for Embedded Systems contains an example device descriptor for use with scllio KX MICROWARE Virtual Console iovcons The low level virtual console driver iovcons appears to the caller to be a
162. n an OS 9 extension module specific to the port In this case the interrupt vector entry contains the usual portion of vector code that switches to the current process system stack and saves the current state of all of the volatile CPU registers on the stack The interrupt code then switches to the system s interrupt stack prior to dispatching to the specialized interrupt controller support code For More Information Refer to Interrupt Controller Support for more information about the port specific extension module Modifying the Interrupt Vector The standard exception code for each of the vectors performs the same series of state saving operations A defined set of registers is preserved on the exception stack prior to calling the C code handler for the given exception The set of general registers saved is defined by the subroutine calling conventions used by the Ultra C C compiler The compiler always treats registers r0 r3 r13 xer ctr lr and ccr as volatile registers and register r1 and r2 as dedicated registers The compiler also uses a caller register save algorithm for subroutine calls The calling block must save the current value of any of the volatile registers it wants to preserve because the called subroutine is always allowed to destroy the content of the set of volatile registers This is why the vector exception handlers preserve these registers The exception code must be written to assume that the content o
163. n input interrupt service routine X ON X OFF flow control keyboard interrupt keyboard quit except it polls the hardware for the next character Parameters path_desc points to the path descriptor device_entry points to the device list entry SETSTAT Set Device Status Syntax error_code setstat T_setstat_pb ctrl_block Scf_path_desc path_desc Dev_list device_entry Description Setstats are wildcard calls that set the device parameters specified by the setstat service requests Many SCF type requests are handled by IOMAN or SCF Any set stat functions not defined by them are passed to the device driver If the function code specified in the control block is not recognized by the driver the driver returns an EOS_UNKSVC unknown service code error Parameters ctrl_block is the I_SETSTAT control block path_desc points to the path descriptor device_entry points to the device entry WX microware TERMINATE Terminate Device Syntax error_code terminate Dev_list device_entry Description The terminate routine performs the following functions 1 De initializes the hardware disabling the device interrupts 2 Removes the interrupt service routine s from the system interrupt polling table Parameters device_entry points to the device list entry WRITE Write a Character Syntax error_code write Scf_path_desc path_desc Dev_list device_entry Description The wr
164. ndmod Find Beginning Of Module Syntax void rom_findmod u_char codeptr u_char xXmodptr Description This service scans back from the specified code pointer until it finds a module header Parameters codeptr points to code within the module modptr points to the returned address of the module header The Core ROM Services KX MICROWARE rom_moddeinit De initialize Low Level System Modules Syntax u_int32 rom_moddeinit Description This service is currently not implemented oe N o OS 9 Porting Guide rom_moddel Delete Module From Module List Syntax u_int32 rom_moddel u_char modptr Rominfo rink 3 Description This service deletes a module list entry from the module list and frees it Parameters modptr points to the low level system module rint points to the rominfo structure XX microware rom_modinit Initialize Low Level System Modules Syntax u_int32 rom_modinit u_char modptr Rominfo Fink Description This routine starts the low level system module Parameters modptr points to a low level system module rink points to the rominfo structure rom_modins Insert Module Into Module List Syntax u_int32 rom_modins u_char modptr Mod_list mleptr Rominfo ran 3 Description This service allocates a module list entry and inserts it onto the module list Parameters modptr points to the low level system module
165. nformation define DEV_SPECIFIC include lt rbsccs edm gt include the EditMod generated header file typedef struct dev_specific dev_specific create dev_specific type Add the header generation entry to the makefile for the driver For example rbsccs h rbsccs edm rbsccs edm rbsccs des S EDITMOD h dev_specific o rbsccs edm rbsccs des Ensure the driver s header file is included by confi des when the descriptor is made Add an include statement if necessary After following these steps make the descriptor using the descriptor makefile Chapter 14 Creating Booters This chapter includes the following topics Creating Disk Booters The Boot Device bootdev Record and Services The parser Module Services The fdman Module Services The scsiman Module Services The SCSI host adapter Module Services Configuration Parameters WX MICROWARE 269 KX MICROWARE Creating Disk Booters After creating and debugging the basic disk driver you will probably want to create a disk booter for the same device You can use the example disk booters as prototypes The basic function of the disk boot routine is to provide the device specific routines needed to load a boot file containing the OS 9 system modules 1 The boot file is established on the disk as a special file by the bootgen utility 2 A target independent module fdman is aware of the standard RBF file system layout and is called by th
166. ng is a description of each subroutine BF Drivers and Descriptors WX MICROWARE Table 13 3 RBF Subroutines Function Description GETSTAT Get device status NIT Initialize device and its static storage area RQ SERVICE ROUTINE Service device interrupts READ Read sector s SHISTAT Set device status TERMINATE Terminate device WRITE Write sector s For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions GETSTAT Get Device Status Syntax error_code getstat void pb Rbfpd pd Dev_list dev Description These routines are wildcard calls used to get the device s operating parameters as specified for the OS 9 get stat service requests Usually all Get Stat codes return with an EOS_UNKSvc UnKnown Service Request error Parameters pb is the status parameter block pd is the path descriptor dev is the device list entry WX microware INIT Initialize Device and its Static Storage Area Syntax error_code v_init Dev_list dev Description The INIT routine must 1 Check for previous initialization It must allocate a lock for the driver in the driver static storage and place it in v_drvr_rsrc_id 2 Initialize device control registers enable interrupts if necessary 3 If the driver uses interrupts place the IRQ service routine on the IR
167. ng notification to preserve and restore the state of a hardware interface shared between high level drivers under the control of the operating system and low level drivers required for remote debugging communications or local console support If no low level drivers require the notification services then the notify module may be omitted i Optional ROM Services Table B 9 Notification Services Function Description dereg_hndir Remove registration for notification handler reg_hndlr Register notification handler For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions OS 9 Porting Guide w o o WX microware dereg_hndIr Remove Registration For Notification Handler Syntax error_code dereg_hndlr Rominfo rinf u_int32 hndlr_id Description This service deregisters a notification handler Parameters sae ei points to the rominfo structure hndir_id is the handler ID returned when the handler was registered reg_hndlir Register Notification Handler Syntax error_code reg_hndlr Rominfo u_int32 priority void handler u_int32 direction void void u_int32 Description parameter parameter hndlr_id This service registers a notification handler Parameters rinf priority handler parameter hndlr_id points to the rom
168. ng the booting process The systype h File The systype h file is an include file used in building several of the low level system modules and OS 9 system modules This file should be viewed as the common location for all port specific hardware definitions and configuration parameters YX micRoware The main sections of the systype h file include e Ticker and real time clock definitions e Low level system module configuration definitions e Hardware specific macros and definitions For support of the bootstrap code it is important to include in the systype h header file any target specific hardware definitions you want to use as you write the hardware initialization routines in the sysinit c source file Such definitions might include hardware specific bit layouts address offsets or initial values The sysinit c File The sysinit c file should contain all special hardware initialization your system requires after a reset or system reboot The sysinit c file consists of these different sections or entry points sysinit sysinitl sysinit2 sysreset The sysinit Entry Point The first entry point sysinit is called almost immediately after a reset by btfuncs a sysinit performs the minimum hardware actions the system may require to enable memory or initialize necessary devices during start up This routine does not return through the typical return machine instruction The return to bt funcs a is made directly by a branch
169. nput Mode Specification A non zero value causes input to operate in insert mode This is input characters are inserted in the current input line A zero value causes input to operate in the type over mode The default is type over mode By using the associated control key SCF allows you to enter insert mode define INSERTMODE PLOFF default to insert mode off XX micRoware Table 9 11 SCF Macros continued Name Description BAUDRATE LUPARI STOPBI TY TS Baud Rate This specifies the baud rate of the device The default is 9600 The various standard baud rate macros are defined in the scf h header file define BAUDRATE BAUD9600 default to 9600 baud Parity of Logical Unit This specifies the parity node of the device The default is no parity The various standard parity macros are defined in the scf h header file define LUPARITY NOPARITY default to no parity Stop Bits This specifies the number of stop bits to be used for transmission The default number of stop bits is one define STOPBITS ONESTOP default to one stop bit Table 9 11 SCF Macros continued Name Description WORDSIZE Bits Per Character This specifies the number of bits per character to be used for transmission The default word size is eight bits per byte define WORDSIZE WORDSIZE8 default to 8 bits byte RTSSTAT
170. nts Description Type Size DEBUG_REVS Structure version u_int16 DEBUG_NAME Default debugger client char name DEBUG_COLD_FLAG Flag the client should be u_int32 called at cold start or not Table B 3 Protoman Configuration Elements Configuration Elements Description Type Size LLPM_REVS Structure version u_int16 LLPM_MAXLLPMPROTOS Max of protocols on u_int16 protocol stack Table B 3 Protoman Configuration Elements continued Configuration Elements Description Type Size LLPM MAXRCVMBUFS Number of maximum u_int16 receive mbuffs LLPM MAXLLPMCONNS Max of low level u_int16 protoman connections LLPM_IFCOUNT Number of hardware u_int32 config entries Table B 4 Low Level Network Interface Config Elements Configuration Elements Description Type Size LLPM_IF_IP_ADDRESS IP address u_int8 1 LLPM_IF_SUBNET_MASK Subnet mask u_int8 1 LLPM_IF_BRDCST_ADDRESS Broadcast address u_int8 1l LLPM_IF_GW_ADDRESS Gateway address u_int8 1 LLPM_IF_MAC_ADDRESS MAC Ethernet u_int8 1 address LLPM_IF_TYPE Type of hardware u_ints8 interface LLPM_IF_ALT PARITY Alternate serial u_int8 port parity LLPM_IF_ALT BAUDRATE Alternate serial u_int8 port baud rate KX MICROWARE Table B 4 Low Level Network Interface Config Elements continued Configuration Elements Description Type Size LLPM IF ALT WORDS
171. o_read Low level driver polled read entry point proto_status j Low level driver status entry point v Level Ethernet Driver KX MICROWARE Table 5 1 Entry Points continued Function Description proto_tconnl Low level driver terminate connection entry point proto_timeout Low level driver timeout entry point proto_upcall Low level driver upcall for interrupt processing proto_write Low level driver write entry point For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions proto_deinstall Low Level Driver De installation Entry Point Syntax error_code proto_deinstall Rominfo rinf Description proto_deinstall1 is the low level driver de installation entry point It takes the driver proto_srvr Off the protoman protocols driver list The service de initializes the chip and frees the memory allocated for the buffers It also removes its name from the notification services list Parameters rink points to the rominfo structure XX microware proto_iconn Low Level Driver Initiate Connection Entry Point Syntax error_code proto_iconn Lipm_conn conn_entry u_int32 index Description proto_iconn is the low level driver initiate connection entry point This service performs the driver related connection specific initialization Parameters conn_entry is not used in the drive
172. of its appropriate subdirectories to build the bootstrap code and low level system modules Some of the subdirectories are disabled by default For the initial target port uncomment the values for the CONSCNFG COMMCNFG PORTMENU and USEDEBUG macros Once this target port directory structure is in place the bootstrap code can be ported Chapter 3 Porting the Boot Code This chapter includes the following topics Porting the Bootstrap Code Configuring the Low Level System Modules Building the Boot Image WX MICROWARE 41 MICROWARE La Porting the Bootstrap Code The source files boot c and all of the files in the lt cPU Family gt subdirectory of the ROM directory are used to build the bootstrap code Figure 3 1 lt MWOS gt 0S9000 Bootstrap Source Code Directories lt Target gt MWOS F OS9000 He Family gt SRC boot c N N ROM ROMCORE ib m SY SiNit C i rom_cnfg h lt CPU ron These files and the port specific sysinit c source file are compiled and linked together with the distributed libraries to build the bootstrap code The distributed libraries include p2privte l p2lib 1 romsys 1 See Appendix A The Core ROM Services for more information about For More Information the distribution libraries To port the boot code you must create additional files to support the source files and libraries The sample target port director
173. ome Ethernet devices You use these drives directly or modify them to support your network device A brief description of the distributed low level system modules grouped by service follows Configuration Modules You can use the configuration modules to configure the boot system These modules provide a way for other low level system modules to retrieve configuration parameters describing how they should function The low level system modules are soft coded to use the configured values retrieved by calling the configuration module services cnfgdata Target specific data module containing the configuration parameters The definitions of these parameters are set in the systype h default des where applicable and config des files Note While all the other low level system modules are organized as OS 9 extension modules cnfgdata is an OS 9 data module cnfgfunc Target independent module that retrieves configuration parameters from the cnfgdata boot data module This module could be Boot Modules XX microware modified to return target specific overrides of the default information in cnfgdata For example you could override cnfgdata values with NVRAM or switch jumper settings These are the modules responsible for selecting the appropriate system boot routine and using it to locate the OS 9 bootfile from the appropriate device bootsys portmenu Target independent module providing two services a booter regist
174. on cons_term shuts the port down by disabling transmit and receive Parameters rinf points to the rominfo record structure cdev points to the console device record for the device cons_write Write Character To Output Port Syntax u_int32 cons_write char Cy Rominfo Cink Consdev cdev Description cons_write writes a character to the output port with no special character processing for a low level serial driver that does not use software handshaking The sample sources also contain the following serial I O module entry points to support the user state Hawk remote debugger For the initial port it is not necessary to include these entry points because the previous functions are sufficient for support of system state operation at the low level The following entry points support the use of low level serial O module while in user state after the system is booted This functionality is required for use of the I O module by the user state Hawk debugger Parameters c is the character written to the output port rinf points to the rominfo record structure cdev points to the console device record for the device WX microware notification_handler Handle Callback from Notification Services Syntax u_void notification_handler u_int32 direction void cdev Description notification _handler issues calls to cons_stat with the CONS_SETSTAT ROMBUG_ON and CONS_SETSTAT ROMBUG_OFF
175. on of software may cause damages far in excess of the value of the copies involved For additional copies of this software documentation or if you have questions concerning the above notice please contact your OS 9 supplier Trademarks OS 9 OS 9000 DAVID FasTrak and UpLink are registered trademarks of Microware Systems Corporation SoftStax and Hawk are trademarks of Microware Systems Corporation Windows Windows 95 and Windows NT are registered trademarks of Microsoft Corporation All other product names referenced herein are either trademarks or registered trademarks of their respective owners Address Microware Systems Corporation 1500 N W 118th Street Des Moines lowa 50325 515 223 8000 Table of Contents Chapter 1 Porting Steps Summary and Reference 9 10 Before Beginning the Port Steps 15 Porting Steps Summary 15 Phase Prepare a port directory 15 Phase Il Create the Low Level System 16 Optional Phase III Set Up Hawk System State Debugging 17 Phase IV Create the High Level System 18 Phase V Adding Features to the Basic Port 19 OS 9 Boot Code Overview 19 Bootstrap Code romcore 20 Low Level System Modules 21 Configuration Modules 22 Boot Modules 24 Serial Communication Modules 25 Low Level Network I O Modules 26 Timer Modules 26 Debugger Modules 29 Notification Module 30 Miscellaneous Module 30 Low Level System Configuration 32 OS 9 Boot Process Overview 32 Power up To the Debugger Prompt
176. onn_entry u_int32 index L1IMbuf rmb Description proto_read is the low level driver polled read entry point It polls the chip and returns if it has a good packet or if it was called with the low level connection entry flag set to indicate nonblocking read and the timer expires The suggested algorithm while waiting for a packet is to periodically check the timer routine if anonblocking read is specified and returns if the timer reaches a value of zero or if it receives a valid packet In the latter case the service processes the Ethernet packet before passing it up the stack Parameters conn_entry is not used in the drivers but is present because the protocols also use the same prototypes This entry point is called by hlproto to turn on off the interrupts It is also called by the notification handler routine index points to the appropriate proto_srvr tcp ip udp slip rmb points to the global mbuf pool proto_status Low Level Driver Status Entry Point Syntax error_code proto_status Lipm_conn conn_entry uU_Int32 code void xps Description proto_status is the low level driver status entry point Parameters conn_entry is not used in the drivers but is present because the protocols also use the same prototypes This entry point is called by hlproto to turn on off the interrupts It is also called by the notification handler routine code specifies what the caller expec
177. oot ml makefile readme txt config des where applicable INIT SYSMODS default des SYSTEMS IRQS TICKER TESTBOOT PORTBOOT optional Real Time Clock Support The real time clock functions for the MWOS 0S9000 SRC SYSMO clock routines are e Get time various real time clock devices are in DS RTC directory The two real time This routine reads the current time from the real time clock device e Set time This routine sets the current time in the real time clock device KX MICROWARE Automatic System Clock Startup The kernel can automatically start the system clock during its coldstart initialization The kernel checks the init module s m_compat word at coldstart If the B_NOCLOCK bit is clear the kernel performs an _os_setime system call to start the tick timer and set the real time This automatic starting of the clock can pose a problem during clock driver development depending on the state of the real time clock hardware and the modules associated with the tick timer and real time clock If the system software is fully debugged you should not encounter any problems The following are common scenarios and their implications 1 The system has a working tick module and real time clock support If the B_NOCLOCK bit in the init module s m_compat byte is clear the kernel performs the _os_setime call The tick timer code is executed to start the tick timer running and the real t
178. or number of the device interrupt Interrupt Level This is the hardware priority of the device interrupt Interrupt Priority This is the software polling priority of the device interrupt Table 13 5 RBF Logical Unit Static Storage Structure continued Name Description v_luopt Device Options This is the device options section A full description of this structure follows the discussion on Disk Drive Information v_reserved Reserved Space reserved for future expansion Disk Drive Information Because RBF supports a wide variety of format options for disk media it maintains information about the current media being processed in the logical unit static storage for the drive The structure definition of the drive information is shown here and a description of each field follows This structure is defined in the header file rbf h tl Note These values should not be changed from the defaults defined in the descriptor source file typedef struct rbf_drv_info idblock v_0 standard ID block stuff gt note alignment here lt lk_desc v_file_rsrc_lk the file list resource lock Rbf_path_desc v_filehd list of open files on drive lk_desc v_free_rsrc_lk free list resource lock struct freeblk v_free pointer to free list structure v_freesearch start search here for free space u_int32 v_diskid disk ID number fd_segment v_mapseg the bitmap segmen
179. ormation Structure continued Name Description v_free_rsrc_lk v_free v_freesearch v_diskid v_mapseg Resource List Lock Descriptor Lock descriptor structure for locking the allocatable resources list List of Allocatable Resources This field points to a data structure representing the areas on the media free for allocation RBF searches this data structure when it allocates space for a file Beginning of Free Memory This field points to the part of the v_free data structure for RBF to start searching when it allocates space for a file Disk ID RBF copies the diskid field from the idblock and stores it in this field It is used to detect when disks have been changed in a disk drive Allocation Bitmap Segment Information This field contains the segment information for the RBF allocation map RBF does not set this field until it needs the allocation map for an allocation or de allocation operation KX MICROWARE Table 13 6 RBF Drive Information Structure continued Name Description v_bkzero Identification Section Pointer This is a pointer to a buffer containing the identification sector Only the driver uses this field RBF never accesses this field v_trak Current Track Cylinder This is the track cylinder over which the head is currently positioned Only the driver uses this field RBF never accesses this field v_softerr Recoverable Error Count This is the numb
180. ow level serial I O module to support the booting process Table 4 1 Entry Points Function Description cons_check Cone Init Sone irg cons_probe cons_read cons stat cons _term cons write notification_handler Check I O Port Initialize Port Polled Interrupt Service Routine for I O Device Probe for Port Read Character from I O Port Set Status on Console I O Device De initialize Port Write Character to Output Port Handle Callback from Notification Services Creating Low Level Serial I O Modules For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions OS 9 Porting Guide 63 WX microware cons_check Check I O Port Syntax u_int32 cons_check Rominfo rinf Consdev cdev Description cons_check interrogates the port to determine if an input character is present and returns the appropriate status Parameters rink points to the rominfo record structure cdev points to the console device record for the device cons_init Initialize Port Syntax u_int32 cons_init Rominfo rant Consdev cdev Description cons_init initializes the port It resets the device port sets up for transmit and receive and sets up baud rate parity bits per type and number of stop bits cons_init also registers a notification handler described be
181. performs the _os_setime Call The tick timer code is executed to start the tick timer but the tick module returns an error because it lacks real time clock hardware The system time is invalid but time slicing occurs You can correctly set the real time once the system is up For example you can run set ime from the startup file or a shell command line For more information about debugging the ticker in a system with a real time clock see Chapter 12 Selecting Real Time Clock Module Support Chapter 12 Selecting Real Time Clock Module Support This chapter includes the following topics Real Time Clock Device Support Automatic System Clock Startup WX MICROWARE 213 KX MICROWARE Real Time Clock Device Support Real time clock devices especially those equipped with battery backup enable the real time to be set without operator input OS 9 does not directly support the real time functions of these devices although the system tick generator can be a real time clock device The real time functions of these devices are used with the tick timer initialization If the system supports a real time clock write the tick timer code so the real time clock is accessed to read the current time or set the time after the ticker is initialized Figure 12 1 Real time Clock Setup Directories and Files OS9000 BOOTS EXAMPLES optional aia lt others gt bootfile ml coreb
182. pplied IP address addr This is used only in proto_install when the driver does a gratuitous ARP informing the world of its hardware address This function can be used in the future for sending ARP requests Parameters psrvr points to the proto_srvr structure addr is the IP address rinf points to the rominfo structure KX MICROWARE in_arpinput ARP Input Processing and Replying Function Syntax void in_arpinput Proto_srvr pPSrvr L1iMbuf mb Rominfo Fant Description in_arpinput is called by arpinput If the ARP request is directed to this function it caches the sender s hardware address and replies to the request with its hardware address If the ARP table is full the request is discarded al Note Currently there is no mechanism to reuse the stale entries This means requests may be discarded if the table is full Parameters psrvr points to the proto_srvr structure mb points to the packet received Pink points to the rominfo structure Creating a Low Level Ethernet Driver Other Functions Additional functions include Table 5 4 Additional Functions Function Description in_broadcast Determines if Address is a Broadcast Address For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions OS 9 Porting Guide 103 WX microware in_broadcast Determines If A
183. pport 215 select tick interrupt device 208 tick timer setup 210 cnfg_svcs optional ROM services 338 cnfgfunc optional ROM services 338 common path descriptor variables pd common 173 communications low level iovcons 204 compare strings parse field 282 COMPAT macro 123 config des RBF file organization 258 RBF macros to define 258 SCF file organization 186 ABCDEFGHIJKLMNOPQRSTUVW XYZ SCF macros to define 186 configuration module 118 configuration parameters recognized by booter modules 303 cons_init initialize port 66 72 CONS NAME macro 120 cons_probe probe for port 67 cons_read read character from input port 73 cons_stat set status on cosole I O device 69 cons _svcs 345 cons_term de initialize port 72 73 cons_write write character to output port 73 console device creating options 140 SCF driver modifying 140 using scllio directory to copy 140 writing SCF driver for 140 console driver creating options 140 console I O device set status 69 console I O module services optional ROM services 345 CONTROL 265 control character mapping table pd_inmap 176 SCF 181 control word pd_cntl 256 controller address PORTADDR 259 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z SCF macro defined 188 cputype 307 C routine sysinitt 49 sysinit2 49 sysreset 49 CTRLRID 267 current byte count in buffer v_incount 165 current byte count in output buffer v_outcount 166 current column position pd col 179
184. ption Begin timing with the timeout value specified Set the counter to the corresponding value Parameters rinf points to the rominfo structure timeout is the value at which to begin the countdown KX MICROWARE Starting the Low Level Timer Module Step 1 Step 2 Step 3 Step 4 Step 5 During the early stages of system bootup the bootstrap code searches for and starts low level system modules included in the boot image The start up entry point for the low level system modules is supplied in a relocatable r file in the distribution This entry point branches to the C function p2start you need to provide for your timer module The start up routine should perform these tasks Ensure no other timer module has been installed Allocate and initialize the timer services record Allocation may be done passively by defining the timer services record as a module global variable Make the entry points for its services available through the timer services record Allocate and initialize any device specific data structure Install the timer services structure into the rominfo record Building the Low Level Timer Module Step 1 Step 2 Create the makefile for your timer module in a properly named subdirectory of your port s ROM directory for example lt Target gt ROM LL lt nnnn gt Use the makefiles from the example ports as a guide Complete the following steps to add your low level timer modul
185. ptor using the descriptor makefile Q Creating an SCF Device Driver AA MIC ROWARE 200 OS 9 Porting Guide Chapter 10 Using Hardware Independent Drivers This chapter includes the following topics Simplifying the Porting Process SCF Driver scllio Virtual Console iovcons WX MICROWARE 201 KX MICROWARE Simplifying the Porting Process An OS 9 driver module is required for your console device If the Microware supplied serial drivers include a driver based on the same device your target platform uses you only need to set up the proper configuration labels for the device within the systype h file The Microware supplied driver and driver specific descriptor sources are located in the MWoS 0S9000 SRC I0 SCF DRVR directory SCF Driver scllio scllio is e ahigh level OS 9 SCF driver satisfying I O requests by calling into a low level serial driver e not associated with any particular hardware device e aport independent module All hardware specific operations are performed by the low level driver called by scllio scllio can be in polled input or interrupt driven input modes The v_pollin flag in the device descriptor controls the input mode Output is always polled As a result it is not intended that scllio replace a high level serial driver targeting the specific serial port Instead scllio is designed to be a useful tool in the porting process Once the low level driver has been writte
186. put characters pd_alf Line Feed Flag This is the automatic line feed flag If it is 0 a line feed character is echoed after every end of record character output by the I_WRITLN service request pd_pause Page Pause Flag This field is the end of page pause indicator If it is non zero an auto page pause occurs upon reaching a full screen of output See pd_page for setting the page length Table 9 7 SCF Path Descriptor Options continued Name Description pd_insm _ READLN Input Mode This field determines the input mode for I_READLN Calls If it is 0 input is in type over mode If it is non zero input characters are inserted at the cursor position and all characters to the right of the cursor are shifted to the right pd_nulls Padding Characters This field specifies the number of null padding characters always 00 to be echoed after a carriage return line feed sequence pd_page Lines per Page This field specifies the number of lines per page or screen pd_tabsiz Tab Size This field specifies the tab size pd_err 1 O Error Status This field contains the most recent I O error status pd_col Current Column Position This field contains the current column position of the cursor KX MICROWARE Table 9 7 SCF Path Descriptor Options continued Name Description pd_time Time Out For READ READLN This field specifies the time out value in ticks for unblocked I_READ and I_REA
187. put flag v_pollin 160 SCF 159 polled output flag v_pollout 161 SCF 159 port combination RBF device drivers 231 port directory structure creating 39 PORTADDR 259 SCF macro defined 188 porting steps summary 15 ports directory diagram 38 PowerPC vector code port 128 PRECOMP 265 PREIOS 124 preporting steps list of 10 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z prerequisites porting 10 previous interrupt mask word v_savirq_fm SCF 159 previous interrupt mask word driver only SCF 159 previous interrupt status driver use v_savirq_dv 163 previous interrupt status SCF use v_savirq_fm 163 PRIORITY 260 SCF macro defined 189 probe for port cons_probe 67 probe verify device bt_probe 276 process wait on I O V_wait SCF 159 PROCS macro 122 PROM load bootstrap image 20 proto_deinstall entry point de install 83 proto_iconn entry point initiate connection 84 proto_install low level Ethernet driver install 85 proto_read read entry point 86 proto_srvr example structure 79 proto_status entry point status low level driver 87 proto_tconn ABCDEFGHIJKLMNOPQRSTUVW XYZ entry point terminate entry point connection 88 proto_timeout entry point timeout 89 proto_upcall entry point upcall for interrupt 90 proto_write write entry point 91 pseudo booters 270 psuedo booter rombreak 23 RAM memory define normal search area 46 RBF device descriptor macros 259 device option definitions 250 macro definit
188. quired to build a device descriptor for a new board You will be referred to more detailed procedures for the specific steps involved in writing an SCF device driver and building a descriptor if Microware does not supply one you can use Create a lt Driver gt directory in the port specific lt Target gt SCF directory where lt Driver gt is the name of the serial device driver chip on your board Create DRVR and DESC directories in the lt Target gt SCF lt Driver gt directory along with makefiles to build the drivers and descriptors You can use the example makefiles as a reference Check the Microware supplied driver and driver specific descriptor sources included in the MwoS 0S9000 SRC IO SCF DRVR directory for one based on the same target device your platform uses If you find a driver matching the chip on your board check the makefiles copied from examples in Step 2 to make certain they point to the correct source files for the device driver Go to Step 6 If you do not find a device driver example for the serial chip on your board see the following sections for information on creating a device driver e Creating SCF Device Drivers for specific information on device driver static storage and subroutines e Using SCF Device Descriptor Modules for information on how the device driver you write will use the SCF device descriptor modules Create a new directory in MWOS 0S9000 SRC IO SCF DRVR for
189. r_name sc85x30 Next the makefile uses EditMod to create the sc85x30 edm file example follows that is included by the primary driver include file sc85x30 h BUILD EDITMOD v SDIR mDEV_SPECIFICS device_specific_des SDIR sc85x30 edm SDIR sc85x30 des MAKERS BUILD sc85x30 des o In addition to the standard fields described in syst ype h you can add specific definitions for particular driver descriptor combinations Use these steps for adding device specific information to a descriptor Create an EditMod source file with the structure definition of the additional information For example in rb5400 des struct dev_specific pointer u_int32 ds_ldrvnam ldrvnam u_int32 ds_scsiopts SCSI options string ldrvnam SCSI low level driver name Change the driver s header file to indicate the driver has device specific information define DEV_SPECIFIC include lt sc8042 edm gt include the EditMod generated header file typedef struct dev_specific dev_specific create dev_specific type Step 3 Step 4 Step 5 Add the header generation entry to the makefile for the driver For example sc8042 h sc8042 edm sc8042 edm sc8042 des S EDITMOD h dev_specific o sc8042 edm sc8042 des Ensure the driver s header file is included by the config des file when the descriptor is made Add an include statement if necessary After following these steps make the descri
190. ractive I O The communications port is used by the debuggers as a download and talk through port The communications port can also be used as the SLIP device for low level network communications with the Hawk remote debugger Source code is provided for several low level serial modules that you can configure and use in your system without modification If your target has a serial device for which no I O module already exists use the example sources as a guide to write your own If both the console port and communications port use the same type of hardware interface you only need to build one low level I O module The distributed low level serial I O module sources are in MWOS SRC ROM SERIAL Create a subdirectory for your own source code if you are building your own I O module Figure 4 1 Low Level Serial I O Source Code Directories for Creating a Module SRC lO lt nnnn gt DEFS ROM HW SERIAL In addition to the directories listed earlier each example port directory contains lt Target gt ROM IO lt nnnn gt directories containing makefiles used to build the low level I O module used in the port You need to create such a directory and makefile for your serial devices in your ports directory Use the example makefiles as a guide Device specific include files lt xxxx gt h are normally kept in the MWOS SRC DEFS Hw directory These are typically chip specific definitions and are to be shared by bot
191. ration Chapter 11 Creating a Ticker 207 208 208 210 211 212 Guidelines for Selecting a Tick Interrupt Device Ticker Support OS 9 Tick Time Setup Tick Timer Activation Debugging the Ticker OS 9 Technical Manual Chapter 12 Selecting Real Time Clock Module Support 213 214 215 216 zie 218 Real Time Clock Device Support Real Time Clock Support Automatic System Clock Startup Debugging Disk Based Clock Modules Debugging ROM Based Clock Modules Chapter 13 Creating RBF Drivers and Descriptors 221 eee 224 224 225 228 230 231 231 243 244 245 250 252 258 259 261 268 Creating Disk Drivers Understanding SCSI Device Driver Differences Hardware Configurations Example SCSI Software Configuration Testing the Disk Driver Creating RBF Device Drivers RBF Device Driver Storage Definitions RBF Device Driver Subroutines Using RBF Device Descriptor Modules Logical Unit Static Storage Initialization Disk Drive Information Disk Device Options Path Descriptor Options Table Building RBF Device Descriptors Standard Device Descriptor Macros RBF Specific Macro Definitions Device Specific Non Standard Definitions Chapter 14 Creating Booters 269 270 272 280 283 287 Creating Disk Booters The Boot Device bootdev Record and Services The parser Module Services The fdman Module Services The scsiman Module Services OS 9 Technical Manual 7 WX MICROWARE 298 The SCSI host adapter Module
192. ration routine and the booter selection execution routine The registration routine installs device specific booter modules onto a list of available booters as either an auto booter or menu booter The booter selection execution routine is called as part of the OS 9 booting process It either selects the appropriate auto booter or prompts you to choose a booter from the registered menu booters to use for booting the system Next it calls that booter to retrieve the OS 9 boottfile passing parameters you enter and any defaults found for the booter in the cnfgdata module Target independent module that retrieves a list of names of configured auto and menu booters from the configuration data module portmenu checks each named booter against the list of available booters and if found registers it through the bootsys registration service lt booter gt override srecord flashb romboot restart rombreak parser Any of the port specific booter modules capable of locating and loading the OS 9 bootfile from its target device During initialization each booter installs itself on a list of available booters Target independent booter module that enables overriding of the autobooter If the space bar is pressed within 3 seconds after the bootstrap message displays a boot menu is displayed Otherwise booting proceeds with the first autobooter Target independent booter module that receives a Motorola S record form
193. re port specific modules that use some counter timer device of the target to provide a polling time out mechanism for other low level system modules The services provided are e Initialization perform any required timer initialization e De initialization de initialize timer e Set time out value set a time out value from the time of the call e Get time out value get the time remaining until the time out expires Debugger Modules The OS 9 configuration provides for either target resident or remote system state debugging depending on the debugging method and tool you select dbgentry Target independent module that provides a hook from the boot code and OS 9 kernel s _os_sysdbg system call to the low level debug server wf Note dbgentry must be present in the low level system for debugging capability dbgserv Target independent debug server module The debug server contains services providing the following debugging facilities Monitoring exception vectors Setting breakpoints Setting watchpoints Executing at full speed until it encounters a breakpoint watchpoint or exception Tracing by single instruction Tracing by multiple instructions mf Note The debug server must also be present in the low level system if any system state debugging is required prior to the OS 9 kernel being executed usedebug Target independent module that retrieves the flag from the configuration da
194. re software dependent You can program some devices to produce different vectors define VECTOR 80 Interrupt Level For the Device The number of supported interrupt levels is dependent on the processor being used When a device interrupts the processor the level of the interrupt is used to mask out lower priority devices define IROQLEVEL 4 WX micRoware Table 13 9 RBF SCF and SBF Common Descriptors continued Name Description and Example PRIORITY Interrupt Polling Priority This value is software dependent A non zero priority determines the position of the device within the vector Lower values are polled first A priority of 1 indicates the device desires exclusive use of the vector A priority of 0 indicates the device wants to be the first device on the polling list OS 9 does not allow a device to claim exclusive use of a vector if another device has already been installed on the vector Additionally it does not allow another device to use the vector once the vector has been claimed for exclusive use define PRIORITY 10 LUN Logical Unit Number of the Device More than one device can have the same port address The logical unit number distinguishes the devices having the same port address define LUN 2 drive number RBF Specific Macro Definitions The following macros are specific to RBF Table 13 10 RBF Macro Definitions Name Description and Example
195. ries referred to in this guide The MWOS structure includes other directories and files For a list of files and directories included in your software distribution refer to your Getting Started With OS 9 for lt target gt Getting Started With OS 9 for Embedded Systems or Getting Started With OS 9 for Wireless Systems Figure 2 1 lt MWOS gt 0S9000 Porting Directories and Files BOOTS PICLIB CMD E OBJS Q J18 pa PIPE ROM IRQS SYSMODS a R TICKER CNFGDATA D O i COMMCNFG INITEXT Il lt nnnn gt ROMCORE mao aeron COMSCNFG EXAMPLES optional eae ea meane lt others gt makefile coreboot ml bootfile ml readme txt config des where applicable TESTBOOT optional Creating Target Port Directories Step 1 Step 2 Step 3 The OS 9 boot code sources driver sources and system modules such as the kernel consist of many files when installed on your system Microware provides example source files for several different types of device drivers including serial tickers and real time clocks You only need support for the hardware platform your target has available so you can ignore drivers that are not relevant Determine the following hardware information before beginning the porting procedure e What I O
196. ription proto_write is the low level driver write entry point When called from the next upper layer protocol module on the stack IP for now the service puts the Ethernet headers in place and hands them to the chip to send out on the wire The service masks the interrupts during the entire processing time and does not return until the packet has been sent out on the wire Parameters conn_entry is not used in the drivers but is present because the protocols also use the same prototypes This entry point is called by hlproto to turn on off the interrupts It is also called by the notification handler routine index points to the appropriate proto_srvr tcp ip udp slip Creating a Low Level Ethernet Driver KX MICROWARE Additional Utility Functions The following utility functions are used with mbufs Table 5 2 Utility Functions Function Description find n init _mbuf Find and initialize an mbuf init eth mbuf Initialize an mbuf For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions OS 9 Porting Guide find_n_ init _mbuf Find and Initialize an mbuf Syntax error code find_n_init_mbuf u_char rmb LIMbuf xmb Description find_n_init _mbuf finds and initializes an mbuf This function returns an ENOBUF error if it cannot find an mbuf Parameters rmb points to the global mbuf pool
197. rmation for DCD false This field holds the process identifier the signal code to send and the associated system path number for the process that made an SS_DCOFF setstat call send signal on DCD false Signal Process Information for DCD true This field holds the process identifier the signal code to send and the associated system path number for the process that made an SS_DCON setstat call send signal on DCD true Table 9 4 SCF Logical Unit Static Storage Fields continued Name Description v_outdev v_pdbufsize v_maxbuff v_insize v_incount v_inbufad Output Device Static Storage Pointer This points to the logical unit static storage structure of the output echo device In most cases a device is its own echo device However it may not be as in the case of a keyboard anda memory mapped video display Path Buffer Size This field contains the size of the path buffer SCF uses for this device Maximum Data For Path Buffer This field is a high water marker for the path buffer The device driver should send an X OFF character to the transmitter when the path buffer fills up to this point Device Input Buffer Size This field contains the size of the input buffer for this device logical unit Current Byte Count in Input Buffer This field contains the number of bytes currently in the input buffer The device driver updates this field as it places characters in the input buffer SCF upd
198. roto_install Parameters rinf points to the rominfo structure ps points to the proto_srvr structure WX micRoware proto_upcall Low Level Driver Upcall For Interrupt Processing Syntax error_code proto_upcall Rominfo rant Proto_srvr pd void C Description proto_upcall1 is the low level driver upcall routine for interrupt processing It is called on the interrupt context from the commonIRgEntry point in hlproto This service is used primarily with receive interrupts If the service receives a valid IP packet it updates the ARP table to eliminate sending out an ARP packet If it is an ARP packet the service processes it replies to it if proto_upcall is the destination address and also saves the sender s hardware address The arp_tblupdate function updates the tables if needed If the service receives an IP packet it calls the proto_upcall entry point of the next protocol on the stack IP for now Before doing any interrupt processing this service restores the interrupt status register and the mask register so it does not miss other packets while processing one Parameters rinf points to the rominfo structure pd points to the proto_srvr structure data packet character being passed This is typecast void because each level typecasts it proto_write Low Level Driver Write Entry Point Syntax error_code proto_write Lipm_conn conn_entry u_int32 index Desc
199. rs but is present because the protocols also use the same prototypes This entry point is called by hlproto to turn on off the interrupts It is also called by the notification handler routine index points to the appropriate proto_srvr tcp ip udp slip proto_install Installs the Low Level Ethernet Driver Syntax error_code proto_install Rominfo rinf u_char globs Description proto_install1 installs the low level Ethernet driver module The service initializes the chip and masks the interrupts It initializes the proto_srvr Structure sets all the entry points and installs itself on the protocol list in the low level protocol manager structure Each driver must allocate the memory for the receive buffers and save the pointer Each driver has to allocate its own pool of mbufs Set the PVR_LLISR_REG_REQ and PRM_LLISR_REG_REQ bits so hlprotoman Can register the LLISRs to run in interrupt driven mode The PVR_DRIVER flag in proto_flags indicates the module is a driver module If the service knows the IP address it sends a gratuitous ARP Parameters rinf points to the rominfo structure globs points to the module global variables You should save this pointer in the proto_globs field of the proto_srvr structure so you can access the module global variables WX micRoware proto_read Low Level Driver Polled Read Entry Point Syntax error_code proto_read Lipm_conn c
200. rs in the header file rom h and appears here for illustration Figure 4 3 Console Device Record Directory lt DEFS Family gt struct consdev idver infoid structure version tag void cons_addr port address of I O device u_int32 cons_probe Rominfo Consdev h w probe service cons_init Rominfo Consdev initialization service cons_term Rominfo Consdev de initialization service u_char cons_read Rominfo Consdev read service u_int 32 cons_write char Rominfo Consdev write service cons_check Rominfo Consdev character check service u_int32 cons_stat Rominfo Consdev u_int32 cons_irg Rominfo Consdev proto_upcall Rominfo void char u_int32 cons_flags device flags u_char cons_csave read ahead stash cons_baudrate communication baud rate cons_parsize parity data bits stop bits cons_flow flow control u_int32 cons_vector interrupt vector cons_priority interrupt priority poll_timeout u_char cons_abname abreviated name cons_name full name and description void cons_data device specific data void upcall_data Consdev cons_next next serial device in list u_int32 cons_level interrupt level int reserved WX microware Low Level Serial I O Module Services The following entry points describe the services required of each l
201. s These modules compose the low level system required to boot the system and provide debugging on the target Each low level system module provides one or more services that may be required for a particular target By compiling these services into separate configurable modules the low level system can be rich and flexible without inflating the memory requirements for the core bootstrap code You can build a minimal system by including only the low level system modules required for booting Bootstrap Code romcore The bootstrap code is made from a number of different files that are compiled and linked together to produce the final binary object code romcore Some of the code is not target platform specific and is supplied in intermediate code form files with i or i 1 suffixes or relocatable object code form files with r or 1 suffixes To create the bootstrap code you need to edit a few source files Next you use the make Command os 9make on Windows to compile and link these files with the other intermediate and relocatable files to create the romcore binary image file Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 WX MICROWARE The bootcode follows these steps to boot OS 9 Initialize the basic CPU hardware and devices to a known stable state Locate and initialize each boot module to make all boot services available Determine the location and extent of the target s RAM and ROM memory Call a s
202. s a section for the init module variables that need to be modified for a particular system For More Information See the OS 9 Device Descriptor and Configuration Module Reference for a list of the init fields and the procedures for configuring the init module See the Getting Started with OS 9 for lt target gt for the init modules specific to your board Init Macros The macros defined here override the default macros contained in the file hO MWOS 0S9000 SRC DESC init des The following macros must be set in the INIT default des file and do not have defaults in the init des file Table 7 1 Init Module Override Macros from INIT default des File Name Description and Example INSTALNAME A processor specific character string used by programs such as login to identify the system type define INSTALNAME Motorola MVME1603 define INSTALNAME PC AT Compatible 80386 TICK_NAME A processor specific character string identifying the tick module name The tick module handles the periodic interrupts for OS 9 s time slicing and internal timings define TICK_NAME tk1603 define TICK_NAME tk8253 RTC_NAME A character string identifying the real time clock module name define RTC_NAME tk8253 SYS_START A character string identifying the name of the first process to start after the system boots define SYS _START CMDS shell1 XX
203. s adjusted to reflect the actual block size allocated addr points to where the address of memory allocated is returned ring is the Rominfo pointer ROM Services KX MICROWARE The definition of the rom_svcs structure resides in the include file MWOS SRC DEFS ROM rom h and appears here for illustration typedef struct rom_svcs idver infoid i void rom_glbldata rom_excpt jt rom_initsp i u_int32 rom_vectors E void rom start u_char kernel_extnd x u_char debug_extnd E u_char rom_extnd int32 use_debug Rominfo rinf char rom_hellomsg int reserved E rom_svcs Rom_svcs id version for rom_svcs global data pointer exception jump table initial stack pointer the vector table reset pe the kernel extension the debugger extension the ROM extension debugger enable routine hello message pointer reserved for emergency expansion Most of the rom_svcs fields are informational The rom_hellomsg field enables runtime customization of the first bootstrap message printed to the console The use_debug services is provided by the usedebug module to indicate if the debugger should be activated just prior to the boot system starting the boot process Module Services The definition of the mod_svcs structure resides in the include file MWOS SRC DEFS ROM rom h and appears here for illustration typedef struct mod_s
204. s each in turn Miscellaneous Module flshcache Target specific boot module that provides cache flushing routines appropriate for the target hardware Low Level System Configuration For each example target platform the file coreboot m1 contains a list of the low level system modules along with romcore to create the boot image For your initial port use the configuration given in the example ports You will need to change the coreboot m1 file to use the Rees ETETE E E E m P DESET e ma ana meterence appropriate low level serial device drivers for your console and communications ports and the appropriate booters and low level communications drivers that apply to your target Note You may also want to replace the target resident RomBug debugger with the modules appropriate for use with sndp and the remote Hawk debugger KX MICROWARE OS 9 Boot Process Overview The booting process occurs in three phases and are similar to the steps you take in porting OS 9 The following sections provide background information on porting and the phases of the boot process Power up To the Debugger Prompt When power is supplied to the processor or when a reset occurs the processor begins executing from a fixed address The initial value in the OS 9 boot code is a label cold This label is defined in the bootstrap source code file bt funcs a Once bt funcs a Starts executing it 1 branches to the label sysinit in the
205. s keep a table in the logical unit static variable storage area containing current track addresses and disk format information for each drive unit The track addresses are used for controllers with explicit seek commands to determine if the head must be moved prior to a read or write operation The format data part of each table entry selects density number of sides etc The INIT routine obtains some initialization data from the device descriptor module Each disk media has similar format information recorded on LBN zero the format utility puts it there Whenever block zero of a floppy disk is read the drive s device static storage is updated with the information actually read This is how the driver automatically adapts to different disk formats Initialization of the static storage must occur prior to access of any other block on the drive RBF Device Driver Storage Definitions RBF type device driver modules contain a package of subroutines that perform block oriented I O to or from a specific hardware controller Because these modules are re entrant one copy of the module can simultaneously run several identical I O controllers IOMAN allocates a driver static storage area for each driver and port combination that may control several drives The size of this storage area is specified in the device driver module header m_data RBF requires some of this storage area The device driver may use the remainder in any manner
206. s struct ptr u_int32 reserved rominfo Rominfo The rominfo structure and all its substructures have an infoid field defined as the type idver typedef struct idver u_int16 struct_id structure identifier struct_ver structure version u_int32 struct_size allocated structure size idver Idver The infoid field provides identification and version information about the structure Modules explicitly allocating structures through a rom_malloc callcan also use the struct_size subfield to save the actual size of the memory segment allocated This is useful when actual size differs from the size requested and for later explicit freeing where the actual size needs to be known The version information can be used to determine the existence of added fields as the structures mature from release to release Hardware Configuration Structure The definition of the hw_config structure resides in the include file MWOS SRC DEFS ROM rom h and appears here for illustration typedef struct union hw_config struct cpu68k_config idver infoid id version for hw_config u_int32 cc_cputype specific cpu type cc_fputype specific fpu type cc_mmutype specific mmu type cc_intctrltype interrupt controller type cpu6sk struct cpu386_config idver infoid id version for hw_config u_int32 cc_cputype specific cpu type cc_fputype specific fpu type cc_int
207. sembly des EditMod description files edm Editmod generated C header file h C header file source code lt Microware intermediate code l code files il Microware intermediate code libraries vl Library files m Macro files ml Module list files including coreboot m1 and boot file ml which create the boot images re Assembly language source from the compiler back end Relocatable object code for linker input created by the assembler 1 Porting Steps Summary and Reference WX MICROWARE Table 1 1 Microware File Name Suffixes continued Suffix Definition tpl Makefile templates none Object binary files W mi Note In general OS 9 does not require file name suffixes However certain utilities such as MACS and cc or xcc do require file name suffixes to determine the mode of operation 14 OS 9 Porting Guide Porting Steps Summary Step 1 Step 2 Step 3 Before you begin this section you should have completed the pre porting steps For More Information If you want more details about OS 9 the modules involved in the porting process and what occurs in OS 9 during the booting process see OS 9 Boot Code Overview Phase Prepare a port directory Create a port directory for your board in lt Mwos gt 0S9000 lt CPU Family gt PORTS where lt MWOS gt is the tree in which you have installed your OS 9 product s and lt CPU Family gt is the name
208. sing the tmode utility typedef struct scf_path_desc struct pathcom pd_common common path descriptor structure Dev_list pd_outdev device tbl pointer for echo device u_char pd_ubuf user buffer base address pd_pbuf path buffer base address pd_pbufpos current path buffer position u_int32 pd_endobuf end of buffer position pd_curpos cursor position counter pd_reqent number of bytes requested by the caller pd_evl readln end of visible line counter u_char pd_echoflag flag if echoing output is ok for this device pd_lost non zero if path has become dead ie data carrier detect lost u_int16 pd_reserved 7 reserved space scf_path_opts pd_opt SCF path descriptor options scf_path_desc Table 9 6 SCF Path Descriptor Fields Name Description pd_common Common Path Descriptor Variables This field is the structure containing the path descriptor variables IOMAN requires for all path descriptors These variables are described in the first chapter of this manual pd_outdev Device Table Pointer for Echo Device SCF uses this field for calling the echo device to echo input and output characters in polled mode KX MICROWARE Table 9 6 SCF Path Descriptor Fields continued Name Description pd_ubuf User Buffer Base Address This field saves the user s buffer pointer on read readin write and writeln requests pd_pbuf
209. sociated vector numbers of the interrupt service routines of the driver The driver may use this array to install its interrupt service routines on the system s interrupt polling table The first entry if any is the read IRQ The second entry if any is the write IRQ This array contains the addresses and associated vector number offsets from the base vector number of the device of the interrupt service routines of the driver The base vector number is usually zero However for some smart devices there can be multiple IRQs The actual vector number value the driver uses to install the routine on the system polling table is the sum of the vector number in the logical unit static storage v_vector and the routine vector offset This array is reserved for future use ing an SCF Device Driver KX MICROWARE SCF Device Driver Entry Subroutines The standard driver subroutines and their parameters follow Table 9 2 SCF Subroutines Function Description ENABLE TRANSMITTER INTERRUPTS GETSTAT NIT RQ SERVICE ROUTINE READ SETSTAT TERMINATE WRITE Enable the device s Ready to Transmit interrupts Get device status Initalize device hardware Service device interrupts Read next character Set device status Terminate device Write a character For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for
210. standard low level serial driver Unlike standard serial drivers however iovcons does not communicate with a serial hardware device Instead iovcons transfers I O requests to the low level communication modules TCP IP stack in the same way daemons supporting the Hawk debugger do The configuration of the low level communication system determines whether the output device used is an Ethernet port or SLIP operating over a serial device iovcons provides a telnetd like interface to the low level system console You can telnet to the target processor board to obtain a TCP IP connection over which the OS 9 boot messages and RomBug input output occurs This removes the need for a direct serial connection to the target by providing a remote console Configuration Since iovcons relies on the low level networking modules it must be initialized after these modules in the boot sequence As a result the low level module list used to build the system must be ordered so references to iovcons and conscnfg appear after the references to the networking modules The following excerpt from an example bootfile ml file illustrates the required ordering Console modules PPC CMDS BOOTOBJS ROM console CMDS BOOTOBJS ROM iosmc CMDS BOOTOBJS ROM commcenfg Communications protocol modules PPC CMDS BOOTOBJS ROM protoman PPC CMDS BOOTOBJS ROM 1lltcp PPC CMDS BOOTOBJS ROM 1llip PPC CMDS BOOTOBJS ROM 1lslip
211. sts that are defined to call the driver and unknown setstat function codes v_terminate This field contains the address of the driver s terminate routine The terminate routine is responsible for performing the actual de initialization of the device hardware SCF calls this routine when an I_DETACH service request is made v_entxirg This field contains the address of the driver s enable transmit interrupts routine The enable routine is responsible for enabling the device s transmitter interrupts so the device can begin its asynchronous output SCF only calls the enable routine when data is available for transmission and the transmit interrupts are disabled For more information refer to the v_outhalt field in the logical unit static storage structure definition Table 9 4 on page 160 v_dev_entry This field points to the device list entry for this device Table 9 1 SCF Device Driver Static Storage continued Name Description v_attached v_irgent v_irgrtns v_rsrvd The driver uses this field to keep track of the number of attach operations performed on the device The driver should increment it every time the init routine is called and decrement it for every terminate call This allows the driver to know when it should truly initialize de initialize the hardware This fields specifies the number of interrupt service routines required by the device driver This array contains the addresses and as
212. t Idblock v_bkzero pointer to block zero buffer u_int32 v_resbit reserved bitmap block if any WX MICROWARE v_trak current track number u_int32 v_softerr recoverable error count v_harderr non recoverable error count struct cachedriv v_cache drive cache information ptr lk_desc v_crsrc_lk cache resource lock u_int16 v_numpaths of open paths on this device u_char v_zerord block zero read flag v_init drive initialized flag Rbf_path_opts v_dopts copy of the default opts u_char v_endflag big little endian flag v_dumm2 3 reserved 1k_desc v_fd_free_rsrc_lk FD free list lock Fdl_list v_fd_free_list list of free FD block structures 1k_desc v_blks_rsrc_lk free block list lock Blockbuf v_blks_list list of free block buffers u_int32 v_reserved 4 reserved f rbif dry info Table 13 6 RBF Drive Information Structure Name Description v_0 ID Block Structure This is a copy of the idblock structure from the identification sector of the media The device driver must copy this information from the identification sector every time it is read v_file_rsrc_lk Open File List Lock Descriptor Lock descriptor structure for locking the open file list v_filehd List of Path Descriptors This field points to a list of path descriptors representing the open files on the drive Table 13 6 RBF Drive Inf
213. t CTRL gt V PASSTHRU 0 0 NULL Table 9 9 SCF Default Mapping continued Function Identifier Function Type Code Size String 0x17 lt CTRL gt IGNORE 0 0 NULL 0x18 lt CTRL gt EDFUNCTION DELINE 0 NULL 0x19 lt CTRL gt PASSTHRU 0 0 NULL OxlA lt CTRL gt EDFUNCTION MOVBEG 0 NULL Ox1B lt ESC gt EDFUNCTION ENDOFILE 0 NULL 0x1C PASSTHRU 0 0 NULL Ox1D PASSTHRU 0 0 NULL Ox1E PASSTHRU 0 0 NULL Ox1F PASSTHRU 0 0 NULL Ox7F lt DEL gt EDFUNCTION DELCHRU 0 NULL KX MICROWARE Building SCF Device Descriptors Step 1 Step 2 Making OS 9 device descriptors involves two steps Modifying the appropriate C macro definitions within the SCF lt Driver gt config des fora specific device descriptor Making the descriptor using the associated makefile The config des file is organized so the macro definitions for a particular descriptor are grouped together For example the following section of config des contains the macros that must be defined macros that do not have pre defined defaults for the SCF term descriptor They are grouped together within a C macro conditional Device descriptor common macros define LUN 1 define DRVR_NAME sc7110 scf macros define IRQLEVEL 0 define PRIORITY 5 define INPUT_TYPE IRQDRIVEN define OUTPUT_TYPE IRQDRIVEN KK KKK KR RK RK KKK A A ROK RK KK ROKK
214. t_mbuf mbuf find and intialize 93 flash load bootstrap image 20 flashb booter support for flash programming 23 flow control 11 flshcach 307 flush_cache 307 FORMAT 262 fputype 307 free block buffers list b_ blks list 250 free block list lock descriptor v_blks_rsrc_Ik 250 free FD block structures list v_fd_free list 250 free memory begins v_freesearch 247 get device status ABCDEFGHtIJKLMNOPQRSTUVW XYZ RBF 233 get time timer_get 111 get_config_data 339 get_partition 285 getnum 281 getrinf 327 GETSTAT RBF 233 SCF 150 global variables Ethernet services 81 goodmodule 315 317 Hawk setup steps 16 heads or sides pd_sid 253 high level drivers 226 host defined 10 interconnection with target 11 host adapter initialize llinit 301 terminate interface IIterm 302 host CPU 225 host adapter module 270 hw_config 307 hwprobe 328 O drivers entry points cons_check 64 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z cons_init 65 cons_read 68 cons_term 72 cons_write 73 I O error status pd_err 179 I O lock identifier v_lockid SCF 160 I O wait flag v_wait 163 READLN input mode pd_insm 179 ID block structure v0 246 ID of last using process v_lproc SCF 159 ID of using process v_busy SCF 159 ID of waiting process v_wake SCF 159 ident 142 identification section pointer v_bkzero 248 in_arpinput arp input processing and replying 102 in_broadcast broadcast address determina
215. ta module indicating whether the debugger is called during system startup You can modify this module to perform target specific debugger configuration instead of using a cnfgdata module KX MICROWARE For More Information Refer to Using RomBug for more information about the available features RomBug Target independent debugger client module that provides interactive target resident debugging using the serial console device for the user interface RomBug uses the I O services available through the console module to read commands and display output and uses the services of dbgserv to perform the required debugging tasks tl Note The use of RomBug requires a low level serial device to be available as the system console sndp Target independent system state network debugging protocol module This module acts as a debugging client on the target invoking the services of dbgserv to perform debug tasks Its user interface however is a low level network connection to a Hawk client on the development host That is sndp is viewed as a debug server from the standpoint of the remote host resident Hawk debugger Wwf Note The use of sndp requires the appropriate low level network driver and protocol modules for the communication link For More Information See the Using Hawk manual for information on the features of the Hawk debugger Notification Module Hawk relies on the low level communi
216. te routine of the specified console device record to output a single character to the associated console device Parameters c is the character to output inf points to the rominfo structure cdev points to the console device record for the console device to be used Example rinf gt cons gt rom_putc ch rinf cdev rom_putchar Output a Character To the System Console Syntax void rom_putchar char C Rominfo rinf Description rom_putchar calls the low level write routine of the console device record configured for use as the system console rom_putchar writes the specified character to the console If the character is a carriage return character 0x0d rom_putchar also writes a line feed character 0x0a to the console Parameters c is the character to output rinf points to the rominfo structure Example rinf gt cons gt rom_ putchar ch rinf WX microware rom_puterr Write Error Code To the System Console Syntax void rom_puterr error _code stat Rominfo rinf Description rom_puterr converts the specified error code to a null terminated ASCII string representation of the form AAA BBB CCC DDD and outputs this string to the system console using the rom_putc service Parameters stat is the value of the error code to be displayed rinf points to the rominfo structure Example rinf gt cons gt rom_getchar status rinf rom_puts
217. tents of the commands data it performs requests for the high level driver The low level module also coordinates all communication requests between the various high level drivers and itself The low level module is often an MPU CPU specific module so it can be written as an optimized module for the target system The device descriptor module contains the name strings for linking the modules together The file manager and device driver names are specified in the normal way The low level module name associated with the device is indicated through the ds_1drvrnaan field in the device specific portion of the device descriptor This offset pointer points to a string containing the name of the low level module Example SCSI Software Configuration An example system setup shows how drivers for disk and tape devices can be mixed on the SCSI bus without interference The setup includes e Micropolis 4221 Hard Disk with embedded SCSI controller addressed as SCSI ID 0 e Archive Viper QIC tape drive with embedded SCSI controller addressed as SCSI ID 4 e TEAC SCSI floppy disk drive with embedded SCSI controller addressed as SCSI ID 6 e Host CPU MVME1603 Uses NCR53C810 or NCR53C825 Interface chip eID of chip is SCSI ID 7 The hardware setup would look like this Figure 13 1 SCSI Setup TEAC FC1 ID 4 SCSI Controllers Archive Viper Micropolis 4221 ID 6 ID 0 Physical Devices WX MICROWARE The high level drivers
218. the device driver Build a new device descriptor for the driver See Building SCF Device Descriptors for specific procedures Step 8 KX MICROWARE Set up the proper configuration labels for the device within the systype h file for the driver and the configuration files for the descriptor See Building SCF Device Descriptors for specific procedures For More Information Refer to the Utilities Reference for more information about EditMod and the ident and fixmod utilities Creating SCF Device Drivers This section describes the data structures and subroutines comprising an SCF device driver The first section describes the driver s static storage structure definition and the second section describes the subroutines required for an SCF driver Before you write a device driver you should also understand how the driver uses the device descriptor This information is explained in the Using SCF Device Descriptor Modules section SCF Device Driver Static Storage This section describes the device driver s static storage structure definition The structure definition of the driver static storage is found in scf h and shown on the following page This structure contains the information SCF needs to initialize and call the device driver Like all other OS 9 device drivers SCF device drivers use a standard executable memory module format with a module type of device driver Every driver maintains a driver static
219. the tick real time clock modules explicitly Use the system state debugger or a ROM debugger to set breakpoints at appropriate places in the clock modules Run the setime utility to access the clock modules Repeat steps three through six until the clock modules are operational Use the following steps to include the clock modules when they are operational Remake the init module so the B_NOCLOCKX flag is clear Remake the bootfile to include the new init module and the desired clock modules Reboot the system WX MICROWARE Debugging ROM Based Clock Modules Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 Step 8 For ROM based systems there are two possible situations e lf the system boots from ROM and has disk support exclude clock modules from the ROMs until they are fully debugged They can be debugged in the same manner as for disk based systems e If the system boots from ROM and does not have disk support exclude the clock modules from the ROMs and download them into special RAM until they are fully debugged Downloading into RAM is required so you can set breakpoints in the modules To debug the clock modules Make the init module with the B_NOCLOCK flag in the m_compat byte set Program the ROMs with enough modules to bring the system up but do not include the clock modules under test Power up the system so it enters the ROM debugger Download the modules to test into the
220. tine issues an event signal or pulse to inform the driver that the interrupt has occurred Drivers can also use the more traditional sleep and signal method by copying the current process ID from v_busy in the driver static storage to v_wake Next it does an indefinite sleep a sleep for O ticks The interrupt service routine then sends a wake up signal to the sleeping process using the ID stored in v_wake XX microware Drivers do not have to be interrupt driven A driver can poll the device waiting for command completion but this hampers time sharing performance If the disk controller cannot be interrupt driven it is necessary to perform a programmed I O transfer If bit 1 in p gt d_cnt1 is clear RBF only requests one block writes If the bit is set RBF may request up to pd_xfersize bytes of data to be written RBF divides pd_xfersize by the block size to determine the maximum number of blocks that can be transferred pd_xfersize is defined in the path descriptor options section of the device descriptor Parameters blks blkaddr pd dev is the number of blocks to transfer is the starting block address is the path descriptor points to the device list entry Using RBF Device Descriptor Modules The RBF device descriptor consists of four parts e The OS 9 module header e The common information required by IOMAN for all descriptors e The path descriptor options e The logical unit static storage Two of thes
221. tion 104 INIT 234 SCF 151 Init module 118 init module creation steps 118 macros definitions 119 init des overriding with macros 119 ABCDEFGHtIJKLMNOPQRSTUVW XYZ init h init module header file 118 init_eth_mbuf mbuf initialize 94 init_tape 291 initext initialization module 50 initial installation software distribution 12 initialize device bt_init 275 initialize device static storage area INIT 234 initialize port cons_init 66 72 initialize timer timer_init 112 initialized drive flag v_init 249 initsccs 292 inmap_entry 181 input buffer address v_inbufad SCF 159 input buffer maximum size v_maxbuff SCF 159 input buffer next in pointer v_infill SCF 159 input buffer next out pointer inempty SCF 159 input control character default map scf des 197 input echo function SCF macro defined 194 input halted flag v_inhalt 161 SCF 159 ABCDEFGHtIJKLMNOPQRSTUVWX Y Z input mode specification SCF macro defined 195 input type flag SCF macro defined 191 INPUT_TYPE SCF macro defined 191 INSERTMODE SCF macro defined 195 INSTALNAME macro 119 interrupt controller PowerPC support 136 interrupt level IRQLEVEL 259 SCF macro defined 188 v_irqlevel 160 244 SCF 159 interrupt mask v_irqmask 163 interrupt mask word v_irqmask SCF 159 interrupt polling priority PRIORITY 260 SCF macro defined 189 interrupt priority v_priority 160 244 interrupt vector special porting instructions 134 v_vector 244 SCF 159
222. tl pd_wpc pd_rwr pd_park pd_lsnoffs pd_xfersize pd_reserved 4 Rbf_path_opts number of surfaces O verify disk writes device format number of cylinders default blocks track default blocks track for trk0 sec0 segment allocation size block interleave offset track base offset block base offset tries size of block in bytes control word first write precomp cylinder first reduced write current cylinder park cylinder for hard disks lsn offset for partition max transfer size in terms of bytes reserved for future enhancements Table 13 8 RBF Path Descriptor Options Table Structure Name Description pd_sid Heads or Sides This indicates the number of surfaces for a disk unit pd_vfy Write Verification This field indicates whether a write is verified by a re read and compare If pd_vfy is e 0 Verify disk write e 1 No verification NOTE Write verify operations are generally performed on floppy disks but not hard disks because of the lower soft error rate of hard disks KX MICROWARE Table 13 8 RBF Path Descriptor Options Table Structure continued Name Description pd_format Disk Type OS 9 supports the following format definitions These are defined in rof h FMT_DBLTRKO Track 0 is doubl
223. tor for handlers to execute until one of them returns a value other than EOS_NOTME in register r3 Device drivers would then register the interrupt service routine on the logical interrupt vector during device initialization instead of the physical vector Another example vmeirg module implements the acknowledge and dispatching code for a VMEchip2 vmepci bridge chip set used on the MVME1608 reference target The interrupts from the VMEchip2 are run through the bridge chip and cascaded into the main interrupt controller As a result the vmeirg module installs its acknowledge and dispatching handler on one of picira s logical interrupt vectors Device drivers servicing the VME interrupts then install their handlers on the logical vectors serviced by vmeirg This demonstrates how cascaded interrupt controllers of differing types can be supported Note The interrupt controller module required for your port should be added to the PREIO extension list of the init module 8 Creating PIC Controllers KX MIC ROWARE 138 OS 9 Porting Guide Chapter 9 Creating an SCF Device Driver This chapter includes the following topics Alternatives for Creating a Console I O Driver Creating an SCF Driver Descriptor Creating SCF Device Drivers SCF Device Driver Entry Subroutines Using SCF Device Descriptor Modules SCF Path Descriptor SCF Control Character Mapping Table Building SCF Device Descriptors eo oOo WX MICROWARE
224. ts should be masked as little as possible and only for critical sections of the device driver Previous Interrupt Status SCF use SCF uses this field for saving the current state of the interrupt status register prior to masking interrupts Previous Interrupt Status Driver use SCF device drivers use this field for saving the current state of the interrupt status register prior to masking interrupts Waiting Process ID This field contains the process identifier of any process waiting for the device to complete I O 0 indicates there is no process waiting XX micRoware Table 9 4 SCF Logical Unit Static Storage Fields continued Name Description v_busy v_lproc v_sigproc v_dcdoff v_dcdon Current Process ID This field contains the process identifier of the process currently using the device SCF uses this field to prevent more than one process from using the device at a time NOTE v_busy is always equal to v_lproc or is zero Last Process ID This field contains the process identifier of the last process to use the device The interrupt service routine sends this process the proper signal when an interrupt or quit character is received Signal Process Information for data ready This field contains the process identifier the signal code to send and the associated system path number for the process that made an SS_SENDSIG setstat Call Send signal on data ready Signal Process Info
225. ts to a software stack If the exception is coming from user state then r1 is assumed to point to the current process user state stack If the exception is coming from system state then r1 is assumed to point into either the IRQ stack or the current process system state stack r2 r3 r4 Upon calling the high level C code exception handler r2 points to the static storage area associated with the handler This is the same static storage pointer specified in the F_IRQ service request used to install the exception handler This register like r2 also contains the pointer to the exception handler s static storage area specified in the F_IRQ service request This is true for all of the exception handlers except the system call vector code This handler leaves r3 unchanged because it is assumed to hold a pointer to the service requestor s parameter block This register for all of the exception handlers contains a pointer to the short stack generated by the vector table code It contains the partially saved state of the processor at the time of the exception The complete content of this stack is described in the regppc h header file located in the MWOS OS9000 PPC DEFS directory This stack image is passed as a parameter to the target C code exception handler to allow handlers to gain access to the conditions of the exception if necessary If additional registers other than the ones saved in the short stack are to be modifi
226. ts to be done It can have the following values SS_IntEnab1e to enable interrupts called by hlproto SS_IntDisable to disable interrupts called by hlproto SS_RombugOn to indicate a change from user to system state called by the notification handler SS_RombugOf f to indicate a change from system to user state called by the notification handler ps points to the proto_srvr structure WX microware proto_tconnl Low Level Driver Terminate Connection Entry Point Syntax error_code proto_tconn Lipm_conn conn_entry u_int32 index Description proto_tconn is the low level driver terminate connection entry point This service does the driver related connection specific termination converse of proto_iconn Parameters conn_entry is not used in the drivers but is present because the protocols also use the same prototypes This entry point is called by hlproto to turn on off the interrupts It is also called by the notification handler routine index points to the appropriate proto_srvr tcp ip udp slip proto_timeout Low Level Driver Timeout Entry Point Syntax error_code proto_timeout Rominfo rinf Proto_srvr PS Description proto_timeout is the low level driver time out entry point This entry point is called by the hlproto thread to provide for any kind of time out needed The sample drivers do not use this and therefore it is nulled out in p
227. ttempting a software reset for example a cache flush It then initiates the proper instructions to reset the system or if such a reset is not supported by the target branches back to the Cold entry point in bt funcs a to initiate the reboot sequence The initext Module The initext module is a separately linked portion of hardware initialization code providing a modular functional extension to the sysinitl1 andsysinit2 routines described previously It is provided in source form enabling an end user to add hardware initialization routines specific to a target configuration that would be inappropriate to include in the base romcore module because of hardware modularity requirements For example a peripheral device implemented on a card plugged into the host bus may require specific initialization immediately following a CPU reset in the case where a bus reset could not be asserted by the processor in the sysreset routine described above This initialization code might be appropriately implemented in the initext module rather than a romcore module since the end user may have obtained the port from an OEM providing the base target platform There are two entry points to the initext module rompak1 and rompak2 When the initext module is present in the system immediately following the romcore module rompak1 would be executed by sysinit1 and rompak2 would be executed by sysinit2 provided those routines attempt to call
228. ugger by calling the sysboot_control routine from romsys 1 If a low level debugger is configured enabled and available it is called at this point by the sysboot_control function The debugger displays a processor register display and a prompt The major steps of this phase are shown in Figure 1 2 The following figure illustrates the first step in the boot process Figure 1 2 Chart of Files and the Subroutines they Contain if present cold bsysinit sysinit sysreturn b sysreturn bl sysinit1 sysinit1 rompak1 rompak 1 return return sysinit2 rompak2 rompak2 return return Debugger Prompt to the Kernel Entry Point On return from the debugger once you have requested booting be continued the bootstrap code 1 calls the boot system to find the OS 9 bootfile sysboot_control invokes the boot service provided by the bootsys module to oversee the location of the OS 9 bootfile by the configured booter s This boot service calls each registered auto booter in turn until one is successful in locating a valid OS 9 bootfile If there are no auto booters or if all fail to find a bootfile you are presented with a menu listing of all registered menu booters and prompted to select one The specified booter is called and the process is repeated until a selected booter is successful in locating an OS 9 bootfile transfers control to the OS 9 kernel The coldstart entry point of the kernel
229. umber of communication ports available on the target and host To complete installation of OS 9 you probably need one serial port for console communication and either one serial or one Ethernet port for debugging communications b Tickers available on the target You need one high level countdown ticker for time slicing You need a second ticker for low level timing if you are using Hawk user state debugging on the running system Test and verify your hardware You need e The target board e Communication cables e Power supply cord e Hardware debugger software Test your hardware before beginning the porting process so you are not trying to simultaneously debug the hardware and the software This manual explains the steps for debugging the port of the operating system but does not tell you how to debug hardware problems While debugging your hardware determine if there are board hardware features to help you in the debugging process For example see if there is an LED you can light or a bell you can ring Figure 1 1 shows a typical host and target interconnection Figure 1 1 One Typical Host and Target Interconnection RS 232 RS 232 CRT Workstation Optional RS 232 PROM aseessa aesmar Programmer mf Note Use 9600 baud or the highest possible data rate for RS 232 links to maximize download speed The default is 9600 baud The X On X Off protocol is used for flow control Step 3 KX MICROWARE
230. upt driven or polled If the device is operated in polled mode SCF calls the driver s write routine to transmit every character define IRODRIVEN 0 define POLLED 1 They are defined in scf n The default for this macro is interrupt driven define OUTPUT_TYPE IRODRIVEN Path Descriptor Buffer Size This specifies the size of the path descriptor buffer for all paths opened to the device The default is 256 bytes define SCFBUFSIZE 256 XX micRoware Table 9 11 SCF Macros continued Name Description NS ZE OUTSIZE KYB KYB KYB DINTR DQUIT DPAUSE Logical Unit Input Buffer Size This specifies the size of the input buffer for the logical unit The default is 256 bytes define INSIZE 256 Logical Unit Output Buffer Size This specifies the size of the output buffer for the logical unit The default is 256 bytes define OUTSIZE 256 Keyboard Interrupt Function This specifies the control key to use for the keyboard interrupt function The default value is lt control gt C define KYBDINTR CTRL C Keyboard Quit Function This specifies the control key to use for the keyboard quit function The default value is lt control gt E define KYBDOQUIT CTRL_E Keyboard Pause Function This specifies the control key to use for the keyboard pause function The default value is lt control
231. ure KX MICROWARE The SCSI host adapter Module Services Access to the host adapter services are through the 11scsi_svcs structure defined in MWOS SRC DEFS ROM scsiman h If a host adapter module requires global variables a pointer can be kept in the reservedz2 field of the 1lscsi_svcs structure Each of the following services would need to make swap_globals calls to set the module globals for the duration of the service Table 14 5 11scsi_svcs Functions Function Description lcmd Execute a raw SCSI command lexec Execute specified SCSI command 1iHit Initializes host adapter interface lterm Terminate host adapter interface For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions llcmd Execute a Raw SCSI Command Syntax error_code llcmd u_int8 comd u_int8 dat u_int32 drive_id Bootdev bdev Rominfo rinf Description llcmd executes the specified SCSI command Parameters cmd points to a raw SCSI command block dat points to the data buffer drive_id is the target SCSI identification bdev points to the host adapter s bootdev record inf points to the rominfo structure WX microware llexec Execute Specified SCSI Command Syntax error _code llexec Scsicmdblk cmd u_int32 atn u_int32 limode Bootdev bdev Rominfo rinf Description llexec
232. ure WX microware out 2hex Display a Hexidecimal Word Syntax void outZ2hex u_short word Rominfo rink Description out2hex displays the hexidecimal representation of a word on the system console device Parameters word is the word for which the hex value is to be displayed rinf points to the rominfo structure out 4hex Display a Hexidecimal Longword Syntax void out 4hex u_long longword Rominfo rinf Description out 4hex displays the hexidecimal representation of a longword on the system console device Parameters longword is the longword for which the hex value is to be displayed rinf points to the rominfo structure WX microware rom_udiv Unsigned Integer Division Syntax unsigned rom_udiv unsigned dividend unsigned divisor Description rom_udiv provides an integer division routine that does not rely on the presence of a built in hardware division instruction Parameters dividend is the number to be divided divisor is the number by which the dividend is to be divided setexcpt Install Exception Handler Syntax u_int32 setexcpt u_int32 vector u_int32 irqsvc Rominfo rant Description setexcpt installs an exception handler on the system exception vector table for the specified exception This is usually used with the set jmp and long jmp C functions to provide a bus fault recovery mechanism prior to polling hardw
233. vcs idver u_int32 void u_int32 rinf void Mod_list char u_int32 int mod_svcs infoid id version for mod_svcs init module as P2 rom_modinit u_char modptr Rominfo rinf deinit module rom_moddeinit insert into list rom_modins u_char modptr Mod_list mleptr Rominfo rinf delete module from list rom_moddel u_char modptr Rominfo rinf find module start ptr rom_findmod u_char codeptr u_char modptr find module list entry rom_findmle u_char modptr Mod_list mleptr Rominfo scan for modules rom_modscan u_char modptr u_int32 hdrchk Rominfo rinf rom_modlist low level module list kernel_name pointer to kernel name string validate module goodmodule u_char modptr u_int32 bootsize u_int32 modsize u_int32 kerchk Rominfo rinf reserved 4 reserved for emergency expansion Mod_svcs The most commonly used services are goodmodule and rom_modscan The goodmodule service is used by most booters to validate the loadfile image The rom_modscan service is used to extend the runtime configurability of the low level system modules WX microware Table A 2 mod_svcs Functions Function Description goodmodule rom_findmle rom_findmod rom_moddeinit rom_moddel rom_modinit rom_modins rom_modscan
234. ver services include device initialization and de initialization read a byte write a byte and get status Each low level serial driver will during module initialization install itself on a list of available serial drivers A low level virtual console driver that is hardware independent because it transfers I O requests to the low level network modules TCP IP stack iovcons provides a telnetd like interface to the low level system console You can use the telnet command to link to the target processor board to obtain a TCP IP connection over which the OS 9 boot messages and RomBug 1 O occurs This removes the need for a direct serial connection to the target by providing a remote console Low Level Network I O Modules protoman LEep Target independent protocol module manager This module provides the initial communication entry points into the protocol module stack Target independent low level transmission control protocol module Target independent low level internet protocol module WX MICROWARE llslip Target independent low level serial line internet protocol module This module uses the auxiliary communications port driver to perform serial I O ludp Target independent low level user datagram protocol module lbootp Target independent low level BOOTP protocol booter module l lt ether gt Target specific low level Ethernet driver module Timer Modules The timer modules a
235. w Low Level Timer Module Directory lt Target gt LL lt nnnn gt LL lt nnnn gt DEFS ROM ROM TIMERS rom h In addition to the source directories each example port directory contains lt Target gt ROM LL lt nnnn gt directories containing makefiles used to build the low level timer module used in the port You need to create such a directory and makefile for your timer module in your ports directory Use the example makefiles as a guide KX MICROWARE The Timer Services Record A timer module establishes a single timer services record for the system This record is used to access the services of the timer module and to maintain any necessary state information The definition of the tim_svcs record is in the header file MwoS SRC DEFS ROM rom h as follows Timer Services Record typedef struct tim_svcs idver infoid id version for tim_svcs error_code timer_init Rominfo initialize the timer void timer_set Rominfo u_int32 set timeout value amp start u_int32 timer_get Rominfo get time left zero expired void timer_deinit Rominfo de initialize timer void timer_ data local data structure u_int32 rom_delay delay loop counter lus delay int reserved reserved for emergency expansion y tim sves Tim sves a W S Creating a Low Level Timer Module Y Pd l a Low Level Timer
236. wind_tape sq_execnoxfer sq_execute Execute a SCSI command without data transfer Execute a SCSI command with data transfer Initializes a sequential device Initializes a direct access device Install a low level SCSI host adapter module Reads a direct access device Rewinds a sequential device Execute a SCSI command without data transfer Execute a SCSI command with data transfer 1 4 Creating Booters KX MICROWARE For More Information Refer to the OS 9 Porting Guide Windows help file included with Hawk for more information about these functions 288 OS 9 Porting Guide da_execnoxfer Execute a SCSI Command Without Data Transfer Syntax error_code da_execnoxfer u_int32 opcode u_int32 blkaddr u_int32 bytcnt u_int32 cmdopts u_int32 cmdtype Bootdev bdev Rominfo rinf Description da_execnoxfer issues a command to direct access devices Parameters opcode is the SCSI command code blkaddr is the direct access device block address bytcnt is the size of the data transfer in bytes cmdopts are option flags booters should use 0 cmdt ype indicates the type of command standard or extended CDB_STD or CDB_EXT bdev points to the booter s bootdev record rinf points to the rominfo structure da_execute WX microware Execute a SCSI Command With Data Transfer Syntax error _code da_execute u_int32 u_int32 u_int32 u_int
237. wing functions e Locates the driver s dispatch table structure within the driver s static storage information by using the m_share field of the driver s module header e Adds this offset value to the beginning of the driver s static storage to locate the shared structure This value is contained in the v_dr_stat field in the device list entry associated with the device and is used by SCF in calling the driver _asm _m_share equ scf_drvr_stat identify the driver s shared statics typedef struct scf_drvr_stat error_code v_init address of driver s v_read address v_write address v_getstat address v_setstat address v_terminate address v_entxirdg address Dev_list v_dev_entry of of of of of of init function driver s read function driver s write function driver s get_sta driver s put_sta driver s termina tus function tus function te function driver s entxirg function i e enable transmitter in terrupts device list entry pointer for device u_int16 u_int32 irqg_entry scef_drvr_stat initialized by SCF before calling drvr v_attached driver attached flag maintained by drvr v_rsrvd 7 reserved for future use v_irgcent number of interrupt service routines v_irgrtns 8 j
238. ystem debugger if one is configured Call the configured system booter module to find the OS 9 boottile Transfer control to the OS 9 kernel Low Level System Modules The romcore bootstrap image is merged with several low level system modules to produce the final boot image to be burned into PROM or loaded into RAM NVRAM or flash memory prior to booting the target system Note romcore is the only part of the system that is not a module Because some of the low level system modules provide services they are supplied as linked memory modules in binary form For some modules both target independent binary modules and source code are provided so you can make target specific changes You should use target independent modules for your initial port of OS 9 As more of the port is accomplished these modules can be rebuilt to more directly target your system For the initial port you need to ensure that low level serial driver modules exist to handle the console I O port and an auxiliary communications port You may be able to use the example drivers for the common serial devices directly If not the example source code provides a guide for creating your own driver If you plan to use Hawk tools for downloading and remote system state debugging you need to ensure an appropriate low level network driver is available A low level SLIP driver was provided for use with your serial port In addition example drivers are provided for s

Download Pdf Manuals

image

Related Search

Related Contents

Early Start IS 66402 Use and Care Manual  Eltako ER12-002-8..230V UC    none SL-STFG Instructions / Assembly  Impulse Response Utility User Manual - Help Library  軟式用プロステイタスオーダーシステムPDFダウンロード  無垢材の取扱説明書  Tempurity System User`s Guide  カタログはこちらから  

Copyright © All rights reserved.
Failed to retrieve file