GRLIB Linux Drivers User`s Manual
Contents
1. write read TX SEND TX RECLAIM TX TX TX Send Use empty Scheduled Handle used Sent Queue of ready descriptors Queue of packet descriptors Queue of transmit SpaceWire packet buffers which has ted SpaceWire buffers waiting for been assigned an packets waiting a descriptor enabled descriptor for user to reuse Figure 2 2 GRSPW Driver internal TX queues GRLIB Linux Drivers User s Manual 8 EROFLEX 2 3 2 1 TX SEND The process of sending a SpaceWire packet data and header is called TX SEND in this document A packet is sent by calling the standard UNIX write function with one or an array of struct grspw_wtxpkt entries Each entry describes one packet buffer see below programlisting and table The length of the write buffer must be a multiple of the size of one entry the MSB bits of the length determines which channel the packets will be sent upon and selects between the RX PREPARE and the TX SEND operation If the driver is out of packet structures used internally in driver all packets will not be sent instead the length returned determines how many packets was added to the send queue GRSPW Write TX Packet Entry SEND PACKET struct grspw wtxpkt int pkt id Custom Packet ID unsigned short flags See TXPKT FLAG above unsigned char resv Reserved unsigned char hlen Header Length Set to zero if none unsigned int dlen Data Length Set to zero if none void hdr2. Header Pointer Address from MMAP Lib void data Data Pointer Address from MMAP Lib attribute packed Table 2 5 GRSPW send TX packet buffers write format struct grspw_wtxpkt Field Description pkt id A user defined packet ID which can be used to identify the packet buffer upon TX RECLAIM This is field is optional and does not affect the operation of the driver flags This field hold the transmission options for one SpaceWire packet See TXPKT_FLAG_ for options One can enable IRQ on DMA transmit operation header and data CRC calculation hlen Determines the length of the header set to zero if no header should be transmitted A length larger than 255 bytes is not allowed dlen Determines the length of the data that will be transmitted The maximum length is limited to 128KBytes due to the memory allocation hdr Pointer to the packet header buffer This is only used if hlen is larger than zero The first hlen bytes are transmitted data Pointer to the packet buffer that contains the data of one SpaceWire packet The first dlen bytes are transmitted 2 3 2 2 TX RECLAIM After packet buffers have been request to be sent assigned a descriptor a SpaceWire packet generated and transmitted the packet buffer taken from the descriptor and put into the sent queue of the driver the packet buffer can be read using the standard UNIX read function This process is called TX RECL
3. EROFLEX GAISLER GRLIB Linux Drivers User s Manual GRLIB Linux drivers manual LINDRV Version 1 0 0 Written by Daniel Hellstrom November 2010 Kungsgatan 12 tel 46 31 7758650 413 11 Gothenburg fax 46 31 421407 Sweden www aeroflex com gaisler EROFLEX GRLIB Linux Drivers User s Manual 2 GAISLER GRLIB Linux Drivers User s Manual Daniel Hellstrom Copyright 2010 Aeroflex Gaisler AB EROFLEX GRLIB Linux Drivers User s Manual lii GAISLER Table of Contents Te ATOMIC HOM EN eee KD enr enter nes none E E nettes orne et 1 1 1 Drivers included in th packag eee sers nnt eni nna Ee antur aun ne PEE ERR 1 TD WREGUIFEMENES RE 1 13 gt Installin E ATES 1 1 4 DEVICE node NUMBESTING eoo ye pete uo ee ore tope I xke uus Ree fuite ee EUR eres COEM e POR RS 1 2 GRSPW2 Space Wite Driver cic A bevecnsecbbeaweedwithee cusuesenbbiedvessbasvadebivcasndeiberes EERE de bise uae GER 2 2 gt TOUR LOG VOTEZ LUE 2 M acs 2 PAM TII qu 2 2 1 2 U semp the drivet 1 io e e ette th tere ERR RH OR Reuse beu a e Eee ss bea canes teste 2 PASO CDI qe em 3 222 Control NIC TE 3 PANES CIL AME EEEE RTE 3 2 3 Packet Transfer Interface ss 5 2 3 1 P cket Reception iiie tree enisi esir nace yapecue E E eiu
4. e 1 Portl always selected Others Both PortO and Port1 core selects between them LINKSTATE Output struct Copies the current link state of the GRSPW core to grspw link state the provided buffer The current link configuration Clock division factors start and run the link state port configuration and which port is currently active is copied TC SEND Argument int This command sets the TCTRL and TIMECNT bits of the GRSPW core if bit 8 is set to one The TCTRL and TIMECNT values are taken from the low 8 bits of the argument After optionally setting the TCTRL TIMECNT a Tick In is generated if bit 9 is set to one TC READ Output int This command stores the current value of the GRSPW core TCTRL TIMECNT bits to the address given by the argument QPKTCNT Output struct Reads the current number of packets in all TX RX grspw qpktent queues of all enabled DMA channels This can be used for debugging of the RX TX process in an application it can also be used to determine the number of packets currently buffered by the driver START None N A Start all DMA activity on all DMA channels The receiver is enabled however packet buffers must be prepared in order to actually receive anything After starting the read write interface of the driver is open See the Packet Transfer Interface on how packets are sent received After start the BUFCFG and CONFIG_SET ioctl commands are not available until stopped again If this command
5. GRSPW commands starts with GRSPW_IOCTL_ which has to be added to the command name given in the table below The data direction below indicates in which direction data is transferred to the kernel Input Argument is an address The driver reads data from the given address Output Argument is an address The driver writes data to the given address Input Output both above cases Argument 32 bit simple Argument no data transferred between kernel user None Argument ignored Table 2 2 ioctl commands supported by the GRSPW Kernel driver Command Data Argument Type Description Direction HWSUP Output struct Copy hardware configuration for the GRSPW core grspw hw sup such as number of DMA Channels if RMAP RMAP CRC is supported by core number of SpW ports etc BUFCFG Input struct Even though the user is responsible for allocating grspw bufcfg memory for packet data header the driver must allocate structures for packet handling The packet structures stores the packet state data header pointers packet number etc This command specifies how many packets maximally can simultaneously be buffer internally by the driver The packet structures are shared between all DMA channels The packet structures are allocated when the START command is issued ENOMEM is returned if driver was not able to allocate as many packet structures as requested CONFIG SET Input struct Configure driver according to input One can
6. configure grspw config promiscuous mode which DMA channels will be used DMA channel configuration register a custom time code ISR handler note that it must be an address to a function in kernel typically to a custom user written module time code RX TX enable and RMAP options destination key RMAP enable RMAP buffer CONFIG READ Output struct Copies the current configuration to the address given grspw config by the argument DMA Channel configuration will EROFLEX GRLIB Linux Drivers User s Manual 4 GAISLER Command Data Argument Type Description Direction only be copied for previously enabled channels for other channels the data is undefined STATS READ Output struct grspw stats The driver gather statistics both globally and for g respective DMA channel All gathered statistics are copied to the user provided buffer STATS_CLR None N A Clears the current gathered statistics Resets all counters LINKCTRL Input struct Set SpaceWire transfer speed clock division factor grspw link ctrl and control the link start link disable link auto start IRQ on link error and disable link on error functions of the GRSPW core See LINKOPTS options PORTCTRL Argument int Select SpaceWire port configuration The GRSPW core may have have support for two SpaceWire ports the port select behavior of the core can be controlled by using this command e 0 PortO always selected
7. fails with the errno ENOMEM packet structures was not able to be allocated due to either not enough memory or too many requested If errno is set to EPERM the driver indicates that the MAPLIB was not satisfied for example not mapped to user space EROFLEX GRLIB Linux Drivers User s Manual 5 GAISLER Command Data Argument Type Description Direction STOP None N A Stops DMA operation this till disable the receiver and transmitter of the GRSPW core After the driver has been stopped TX SEND and RX PREPARE operation will result in error EBUSY but the RX RECEIVE and TX RECLAIM operation will still be working so that the user can read out all packet buffers By setting the appropriate flags in the packet information it is possible to determine if a packet has been received transmitted or not 2 3 Packet Transfer Interface The packet transfer interface is used to send and receive Space Wire packets on DMA channels The GRSPW core is configurable how many DMA channels it has a core may have from one up to four DMA channels This interface is open to the user when DMA operation has been started from the control interface START trying to access the interface when it is not open will result in an error and errno will be set to EBUSY Since the GRSPW driver does not manage packet buffers itself but relies on MAPLIB and the user for that the user must prepare the driver with ready RX buf
8. on GRLIB Linux Drivers User s Manual 10 EROFLEX 3 SpaceWire Router APB Register Driver 3 1 Introduction This section describes the Linux Aeroflex Gaisler SpaceWire Router APB registers kernel driver It provides user space applications with a SpaceWire Router configuration interface The driver allows the user to configure the router and control the Space Wire links The SpaceWire router is accessed using the standard UNIX ioct1 routine 3 1 1 Sources The GRSPW driver sources are provided under the GPL license they are available in the GRLIB driver package as described in the table below Applications should include the GRSPW Kernel Driver header file All files are relative the base of the driver package Table 3 1 SpaceWire Router driver sources Location Description spw grspw_router c SpaceWire Router APB Registers Driver include linux grlib grspw_router h SpaceWire Router APB Registers header 3 1 2 Using the driver Applications wanting to access SpW Router registers from user space should include the Router driver header file Each SpW Router core is accessed using a single major minor number The Major Minor numbers are determined by the driver package configuration see Section 1 4 3 1 3 Examples Within the GRLIB driver package there is a user space example of how this driver can be used the example file is named spwrouter custom config c 3 2 Control Interface 3 2 1 Overv
9. packet structures can be configured through the control interface 2 3 1 1 RX PREPARE The process of preparing the GRSPW driver with new packet buffers is called RX PREPARE in this document It is done by calling the standard UNIX write function with one or an array of struct grspw_wrxpkt entries Each entry describes one packet buffer see below programlisting and table The length of the write buffer must be a multiple of the size of one entry the MSB bits of the length determines which channel the packet buffers are for and selects between the RX PREPARE and the TX SEND operation If the driver is out of packet structures used internally in driver all packet buffers will not be prepared instead the length returned determines how many packets was added to the ready queue GRSPW Write RX Packet Entry PREPARE RX BUFFER struct grspw wrxpkt int pkt id Custom Packet ID unsigned short flags See RXPKT FLAG above unsigned short resvl Reserved must be zero void data Data Pointer Address from MMAP Lib The buffer must have room for max packet attribute packed Table 2 3 GRSPW prepare RX buffers write format struct grspw_wrxpkt Field Description pkt id A user defined packet ID which can be used to identify the packet buffer upon RX RECEIVE This is field is optional and does not affect the operation of the driver flags Set to RXPKT FLAG IE if this packet should g
10. provided buffer EROFLEX GRLIB Linux Drivers User s Manual 12 GAISLER 4 MAPLIB Device Memory Driver 4 1 Introduction This section describes the Linux MAPLIB kernel driver It provides user space applications with a possibility to memory map a configurable number 128 KBytes blocks of memory to user space The memory is direct memory access DMA capable and can therefore be used in other GRLIB drivers which implements user provided device memory buffers In order for memory to be DMA capable a number of things must be satisfied for example that memory is linear with one DMA operation and that the cache is handled correctly Currently the MAPLIB driver memory maps with the memory management unit MMU cacheable bit set this means that the driver will not work for systems with lacks data cache snooping unless flush is performed by the using driver Memory is mapped and unmapped to user space using the mmap mmap2 and unmap functions The functions are described in the man page of respective function The driver provides a secure way of mapping calling the using drivers when the memory is unmapped or changed in any other way The using driver should then stop all DMA operation to that memory area and report an error to the user The driver s main intention is to let other drivers more easily implement zero copy between user space and kernel space both between the the same device instance and between different device instance an
11. setup Configure Memory MAP Library and allocate all need memory all previous if any memory mapped pages must be unmapped otherwise and error will occur and errno set to EINVAL MMAPINFO Output struct Get Current MMAP Info from Driver this tells the user maplib mmap info how to memory map the memory into user space It tells E the user how many blocks their size and the offset into the MAPLIB device memory mmap should try to map from Mapping Interface Once the driver has been configured using the control interface the memory must be mapped to the user space process address space before any other driver or the application itself can start using the DMA capable memory Once the memory is used by a device driver the driver will be signaled if munmap or close is called upon the MAPLIB memory device it will also be signaled if a process is terminated The memory must be mapped in one mmap call creating one linear memory mapping in user space However in physical address space the memory is linear in blocks of 128KBytes The MMAPINFO command reveals how large and at what offset the device memory is located within the MAPLIB device after it has been configured using SETUP Below is an example how to memory map struct maplib mmap info mapi unsigned int start end int fd fd open dev maplib0 O_RDWR if fa lt 0 printf Failed to open MMAPLib n return 1 CONFIGURE MAPLIB HERE USIN
12. writing the configuration bit router config of the Control Status register setting the Instance ID Start up Clock Divisor Timer prescaler and the timer reload registers CFG GET Output struct Reads the current router configuration into the user router config specified memory area ROUTES SET nput struct Configure the 224 words long router table router routes ROUTES GET Output struct Copy the current 224 words long router table to user router routes provided buffer PS SET Input struct router ps Configure the port setup registers according to user buffer PS GET Output struct router ps Copy the current port setup registers to user buffer WE SET Argument int If the argument s bit zero is one then the WE bit in the configuration write enable register is set otherwise it is cleared This enabled the user to write protect the current configuration PORT Input struct router port Write and or Read in that order the port control and Output m port status registers of one port of the SpaceWire router The 1ag field determines which operations should be performed See ROUTER PORTFLG The port field selects which port is to be written read CFGSTS SET Argument unsigned int Writes the Config Status register CFGSTS GET Output unsigned int Copies the current value of the Config Status register to the user provided buffer TC GET Output unsigned int Copies the current value of the Time code register to the user
13. AIM in this document The driver will fill the user provided read buffer with packet buffer information according to the struct grspw rtxpkt memory layout See below programlisting and table Each entry describes one packet which may have been successfully sent The length of the read buffer must be a multiple of the size of one entry the MSB bits of the length determines which channels bit mask of channels to reclaim packets from and selects between the RX RECEIVE and TX RECLAIM operation GRSPW Read TX Packet Entry RECLAIM TX BUFFER struct grspw rtxpkt int pkt id Custom Packet ID unsigned short flags See TXPKT FLAG above unsigned char dma chan DMA Channel 0 3 unsigned char resvl Reserved must be zero attribute packed GAISLER GRLIB Linux Drivers User s Manual 9 EROFLEX Table 2 6 GRSPW reclaim TX packet buffers read format struct grspw_rtxpkt Field Description pkt id A user defined packet ID which can be used to identify the packet buffer upon TX RECLAIM This is field is optional and does not affect the operation of the driver flags This field hold the transmission parameters for one SpaceWire packet See TXPKT FLAG If the the packet was sent a descriptor with the data header was enabled the TXPKT FLAG TX bit is set if a link error occurred TXPKT FLAG LINKERR bit is set dma chan Indicates which DMA channel 0 3 this packet was sent
14. G MAPLIB IOCTL SETUP Get MMAP information calculated by driver if ioctl fd MAPLIB IOCTL MMAPINFO amp mapi printf Failed to get MMAPINFO errno d n errno return 1 Map all SpaceWire Packet Buffers start mapi buf offset end mapi buf offset mapi buf length Memory MAP driver s Buffers READ and WRITE adr mmap NULL mapi buf length PROT READ PROT WRITE MAP SHARED EROFLEX GRLIB Linux Drivers User s Manual 14 GAISLER fd start if unsigned int adr Oxffffffff printf MMAP Bufs Failed p errno d x n adr errno mapi gt buf_ length return 1 EROFLEX GRLIB Linux Drivers User s Manual 15 GAISLER 5 Support For Support contact the Aeroflex Gaisler support team at support gaisler com
15. arde ie esse end rods re Ere 5 2 3 2 Packet Transmission ii cesses secet en nee lie eme EERE AU E CE tions ent 7 3 SpaceWire Router APB Register Driver sise 10 CRDI TEE Seawiag etna thin cube Genes E E EREE 10 SINE REI T 10 3 1 2 Sura 10 SUBcMD ciu Ae uses amine initie seine 10 3 2 Control Interface m 10 SPAN Ica Ur cm 10 4 MAPLIB Device Memory Driver eee eee eerte re ree n Rer ege hee a den a Ero e Ree e Ene rye EE e Ree ERR 12 AA rcr METTRE TEC 12 Zu IIIIm EET 12 4 1 2 Using the dryer eorr ire apes evo eee dp Pene ed eene veto bee bte stie eig 12 CN ED c E H 12 42 Control Interface e br e M tune adapt avec sedis RO petat sie CARE tiennent 13 4 3 Mapping Interface E 13 De SUPPOM reodere es 15 EROFLEX GRLIB Linux Drivers User s Manual 1 GAISLER 1 Introduction 1 1 1 2 1 3 1 4 The purpose of the GRLIB Driver package is for Aeroflex Gaisler to provide Linux drivers for GRLIB cores that does not really benefit from being part of the official kernel tree or for other reasons no part of the official kernel tree SpaceWire for example does not have a generic driver model in Linux Drivers can be built outside of the kernel source tree as modules or within the kernel by installing the drivers into the kernel sources tree Currently the drivers has not been tested as modules so for the time being please install the dr
16. be zero int dlen Data Length void data Data Pointer Address from MMAP Lib attribute packed Table 2 4 GRSPW receive RX packet buffers read format struct grspw rrxpkt Field Description pkt id A user defined packet ID that was given to the driver together with the packet buffer in RX PREPARE flags This field indicates if the data buffer contains a SpaceWire packet RXPKT_FLAG_RX and if transfer errors where encountered during the reception Truncated EEOP Header CRC error Data CRC error dma chan Indicates which DMA channel 0 3 received this packet dlen The length of SpaceWire packet that was received into the packet buffer pointed to by data data Pointer to the packet buffer that contains one SpaceWire packet The flags field bit RXPKT FLAG RX is set if a the buffer contains a SpaceWire packet other flags may also have been set to indicate some sort of SpaceWire transmission error 2 3 2 Packet Transmission The packet transmission interface works basically the same as the packet reception interface The MSB bits of the length determine that TX SEND and TX RECLAIM should be used instead of the RX operations See the previous RX section introduction The packet queues are named differently as indicated in Figure 2 2 the TX scheduled queue also fits as many packets as there are descriptors however the TX descriptors are 64 in number instead of 128 for RX
17. d even between device instances of different drivers For example a SpaceWire packet received on GRSPW 0 may be sent on GRSPW 2 without copying the actual data or for example parts of a SpaceWire packet received on GRSPWL 1 may be sent to ground using the driver for GRTM O device Blocks of 128KBytes are allocated within the Linux Kernel in low memory The amount of memory allocated is configurable through the standard UNIX ioct1 interface of the MAPLIB driver 4 1 1 Sources The MAPLIB driver sources are provided under the GPL license they are available in the GRLIB driver package as described in the table below Applications should include the MAPLIB Driver header file AII files are relative the base of the driver package Table 4 1 MAPLIB driver sources Location Description misc maplib c Device memory library include linux grlib maplib h Device memory library header 4 1 2 Using the driver Applications wanting to access DMA capable memory from user space using the MAPLIB device driver should include the MAPLIB driver header file The amount of memory requested Debug output is available through the proc kmsg interface and additional debug output can be enabled by defining MAPLIB DEBUG in the driver sources maplib c Each MAPLIB driver is accessed using a major minor number The driver has a build time configurable number of memory pools device nodes The Major Minor numbers are determined by the d
18. e scheduled for future reception There are two different states of a DMA channel when descriptors has been prepared and enabled for transmission and when there are no enabled descriptors out of buffers In the latter case the core can be programmed to discard incoming packets or to wait for new enabled descriptors packet buffers that is controlled through the control interface see NO SPILL option in GRSPW hardware documentation Packet reception basically comes down to enabling descriptors with new empty buffers The driver must process the core s descriptor table to handle received SpaceWire packets and enable unused descriptors with new packet buffers That process might be triggered in two different ways DMA receive interrupt the driver will schedule work to process the descriptor table later on in non interrupt context The user calls RX PREPARE or RX RECEIVE The user can configure the behavior of the first case by controlling how interrupts are generated The driver can generate interrupt after every N number of packets have been received The user can also control it EROFLEX GRLIB Linux Drivers User s Manual 6 GAISLER completely custom by setting N 0 and enabling interrupts on a packet basis see RX PREPARE If the driver is not able to process the RX descriptor table in time the transfer rate will drop or packets will be discarded Since the user might not be able to call RX PREPARE and RX RECEIVE often enough
19. e the MAPLIB header file Debug output is available through the proc kmsg interface and additional debug output can be enabled by defining GRSPWU_DEBUG in the driver sources gr spw_user c EROFLEX GRLIB Linux Drivers User s Manual 3 GAISLER Each GRSPW core is accessed using a single major minor number regardless of how many DMA channels the core has The Major Minor numbers are determined by the driver package configuration see Section 1 4 2 1 3 Examples Within the GRLIB driver package there is a user space example of how this driver can be used 2 2 Control Interface 2 2 1 Overview The Control interface provides information about the GRSPW hardware configuration of the driver reading current statistics link control and status selecting port if two ports are available handling time code transmission and starting stopping DMA channels The Packet Transfer Interface can not be used unless the DMA channel has been started the link state is independent of starting stopping DMA channels The link state will of course have an impact on what is transferred over SpaceWire it will affect all DMA channels Since SpaceWire has flow control packets will buffer up when the link state goes from run state to any other state The user is expected to handle the link state The control interface is accessed using the standard UNIX ioct1 routine In the table below all currently supported ioct1 commands and their argument is listed All
20. enerate a interrupt when a SpaceWire packet was received to this packet buffer Interrupts can be controlled using the control interface data Pointer to the packet buffer that the driver will store one received SpaceWire Packet to The address must be within the range that was memory mapped with MAPLIB a user space address is expected GRLIB Linux Drivers User s Manual 7 EROFLEX 2 3 1 2 RX RECEIVE After packet buffers have been prepared assigned a descriptor a SpaceWire packet received the packet taken from the descriptor and put into the receive queue of the driver the packet can be read using the standard UNIX read function This process is called RX RECEIVE in this document The driver will fill the user provided buffer with packet buffer information according to the struct grspw_rrxpkt memory layout See below programlisting and table Each entry describes one packet which may have a valid SpaceWire packet in the packet buffer pointed to be data The length of the read buffer must be a multiple of the size of one entry the MSB bit of the length determines which channels bit mask of channels to receive packets from and selects between the RX RECEIVE and TX RECLAIM operation GRSPW Read RX Packet Entry RECEIVE struct grspw rrxpkt int pkt id Custom Packet ID unsigned short flags See RXPKT FLAG above unsigned char dma chan DMA Channel 0 3 unsigned char resvl Reserved must
21. fers to be able to receive packets in the future The user is also responsible to reuse sent packet buffers in order for the user to know when a packet buffer has been sent and is ready to be reused the driver let the user read back reclaim TX buffers The interface supports four basic operations that can be performed independently per DMA channel see list below All packet operations are completed in the order they are given to the driver for example if multiple packet buffers are requested to be sent the order in which the buffers are sent and also reclaimed is the same as the order they where given to the driver using the write function e RX PREPARE prepare the driver with RX packet buffers RX RECEIVE get received SpaceWire packets the packets are placed in previously prepared packet buffers TX SEND send one or multiple packets by giving TX RECLAIM get used sent packet buffers from the driver previously sent The above operations are implemented using the standard UNIX read write file operation calls Since both read and write takes different input depending on which of the two operation is requested the MSB 16 bit of the length is used to determine operation and which DMA channels are involved in the request See GRSPW READ and GRSPW WRITE definitions in header file 2 3 1 Packet Reception When the SpaceWire link is in run state and DMA operation has been started from the control interface packets buffers can b
22. her Linux version The kernel that must be used is taken from www kernel org and may require patching using the Aeroflex Gaisler unofficial patches distributed until they are included in the official kernel tree Please check which GIT version is required used in the VERSION file Installing Please see the README file included in the driver package for installation instructions Device node numbering The GRLIB drivers are assigned major numbers from the LOCAL EXPERIMENTAL USE series defined in the 1inux 2 6 Documentation devices txt The driver major number and device minor numbers assigned is determined by the include linux grlib devno h header file in the GRLIB driver package Device nodes are normally created somewhere in dev in the local file system nodes can be created with the mknod utility GRLIB Linux Drivers User s Manual 2 EROFLEX 2 GRSPW2 SpaceWire Driver 2 1 Introduction This section describes the Linux GRSPW kernel driver It provides user space applications with a Space Wire packet interface The driver is implemented using the GRSPW Kernel library for GRSPW device control and DMA transfer and it uses the memory map driver MAPLIB for ensuring that device memory DMA memory has been setup properly The driver supports the GRSPW2 and the DMA interface of the Aeroflex Gaisler Space Wire Router By splitting the GRSPW driver into three parts it is possible to reuse specific parts of the driver source For e
23. iew The SpaceWire router can be configured using the control interface described in this section The interface is router hardware specific and a good knowledge of the hardware is necessary See hardware documentation The data structures are described in the header file available in the GRLIB driver package The control interface is accessed using the standard UNIX ioct1 routine In the table below all currently supported ioctl commands and their argument is listed All router commands starts with GRSPWR_IOCTL_ which has to be added to the command name given in the table below The data direction below indicates in which direction data is transferred to the kernel Input Argument is an address The driver reads data from the given address Output Argument is an address The driver writes data to the given address Input Output both above cases Argument 32 bit simple Argument no data transferred between kernel user None Argument ignored Table 3 2 ioctl commands supported by the GRSPW Kernel driver Command Data Argument Type Description Direction HWINFO Output struct Copy hardware configuration of the router core such grspw hw info as number of SpaceWire ports number DMA port number of FIFO port etc EROFLEX GRLIB Linux Drivers User s Manual 11 GAISLER Command Data Argument Type Description Direction CFG_SET Input struct Configure the router by
24. iver sources into the kernel andlink them into the kernel After installing the package into the kernel source tree a menu named GRLIB Drivers will appear in the bottom of the Device Drivers directory in the kernel configuration GUI The Kernel Configuration GUI is invoked as usual linux 2 6 make ARCH sparc CROSS COMPILE sparc linux xconfig If the drivers are built outside of the kernel tree and installed into the filesystem for loading during runtime the building process is as follows grlib drivers make KERNELDIR path to kernel linux 2 6 sources Note that the kernel sources provides a way to install modules using the make target modules install together with INSTALL MOD PATH path to rootfs Drivers included in the package Below is a list of which drivers are currently distributed in the GRLIB Linux driver package GRSPW2 Kernel Library for custom kernel driver or GRSPW Driver e GRSPW2 Driver Char device accessible from Linux User space GRSPW ROUTER APB Register Driver MAPLIB Device memory handling Enables a user to memory map blocks of linear memory that can be used by device drivers for DMA access GRLIB Drivers that implement zero copy to user space and between device nodes though user space require the MAPLIB char driver Requirements The GRLIB Drivers package is built against one specific Linux release it is expected that drivers may fail to build or does not function properly if used under anot
25. on high bit rates or small packets the DMA receiver interrupts can be used to start processing of descriptors On DMA receive interrupt the driver will schedule a work queue that will process the descriptor table in order to enable new packet buffers the user must have prepared buffers on beforehand Prepared packets will be buffered temporarily in the READY queue until unused descriptors are available Received packets will be buffered in the same order as the SpaceWire packets was received in the RECV queue See Figure 2 1 Note that if N is set to a higher number than the number of RX descriptors 128 or when it is disabled the descriptor table may not contain any enabled descriptors until RX PREPARE or RX RECEIVE is called by the user write read RX PREPARE RX RECEIVE RX RX RX Ready Use empty S cheduled Handle used Received Queue ofunused descriptors Queue of packet descriptors Queue ofreceived ready packet buffers which has SpaceWire buffers waiting for been assigned an packets waiting a descriptor enabled descriptor for user to read Figure 2 1 GRSPW Driver internal RX queues The driver internal RX queues are all link lists of FIFO type The RX schedule queue can hold a maximum of 128 number of descriptors supported by GRSPW at time of writing packets the other queues does not have any limitation except from the number of packet structures that the driver use internally to describe the packets The number of
26. only linear addresses can be used There are other issues as well that must be solved they are taken care of in the MAPLIB driver If the SpaceWire router DMA interface is the underlaying hardware some of the parts described here does not affect the hardware at all For example the link controlling options are of course not implemented at the DMA interface One can control the SpaceWire router s link by using the SpaceWire router driver instead 2 1 1 Sources The GRSPW driver sources are provided under the GPL license they are available in the GRLIB driver package as described in the table below Applications should include the GRSPW Kernel Driver header file All files are relative the base of the driver package Table 2 1 GRSPW driver sources Location Description spw grspw c GRSPW Kernel library spw grspw_user c GRSPW Kernel Driver misc maplib c Device memory library include linux grlib grspw h GRSPW Kernel library header include linux grlib grspw user h GRSPW Kernel Driver header include linux grlib maplib h Device memory library header 2 1 2 Using the driver Applications wanting to access GRSPW devices from user space should include the GRSPW kernel driver header file if the include path is set correct it will include the kernel library header as well As mentioned above the user is also responsible to setup device memory using the MAPLIB driver so the application should also includ
27. river package configuration see Section 1 4 One can list the current address space mappings of a process by concatenating the proc PROCESS NUMBER maps Reading the file after the mapping processes is completed will reveal the mapping range and access permissions and so on 4 1 3 Examples Within the GRLIB driver package there are at the time of writing two examples one example using the MAPLIB driver only teset_maplib c and one SpaceWire example which demonstrates how the MAPLIB can be used in a real application using the GRSPW driver EROFLEX GRLIB Linux Drivers User s Manual 13 GAISLER 4 2 Control Interface 4 3 The control interface is accessed using the standard UNIX ioct1 routine In the table below all currently supported ioctl commands and their argument is listed All MAPLIB commands starts with MAPLIB IOCTL which has to be added to the command name given in the table below The data direction below indicates in which direction data is transferred to the kernel Input Argument is an address The driver reads data from the given address Output Argument is an address The driver writes data to the given address Input Output both above cases Argument 32 bit simple Argument no data transferred between kernel user None Argument ignored Table 4 2 ioct 1 commands supported by the MAPLIB Kernel driver Command Data Argument Type Description Direction SETUP Input struct maplib
28. xample the GRSPW kernel library does not depend on MAPLIB or the GRSPW Kernel driver this makes it possible to create a custom GRSPW kernel module without the involvement of user space using the kernel library only The MAPLIB does not either depend on the other parts hence it can be used solely in other drivers or together with other drivers This makes it for example possible to receive a SpaceWire packet and transmitting it using a driver for another interface also supporting the MAPLIB driver The driver provides two different types of interfaces through the standard UNIX access routines open close ioctl read write one GRSPW device control interface and one packet transfer interface The control interface is accessed using ioct 1 whereas the packet transfer interface is accessed using read and write The actual packet data transferred on SpaceWire is not read or written using the read and write routines instead pointers to the data and header are interchanged between kernel space the driver and user space the application Transferring only addresses to data header allows the driver to be zero copy all the way from user space to actually sending the packet over SpaceWire however some care must be taken to what memory is used For example even though memory seems to be linear i user space it might not be linear in physical address space due to the memory management unit MMU setup and when the GRSPW core is doing direct memory access DMA
Download Pdf Manuals
Related Search