Shared Software Requierments (Interface Specification)
$Revision: 1.24 $ $Date: 1999/01/27 14:35:21 $
CONTENTS
========
1) Purpose
2) Include Order and Common Data Base Definition
3) Module Dependencies
4) Define Description
5) Variable and Structure Description
6) Function Description
7) History
***
(1) PURPOSE
===========
This document describes all defines, variables and functions
required by shared software modules.
***
(2) INCLUDE ORDER AND COMMON DATA BASE DEFINITION
=================================================
Sample 'C' File (shared source):
#include "h/skdrv1st.h" /* Driver Specific Definitions */
#include "h/sktypes.h" /* Type Definitions */
#include ".../..." /* All header files required by this 'C' file*/
#include ".../..." /* only, has to be included now */
#include "h/skdrv2nd.h" /* Adapter Control- and Driver specific Def. */
---
skdrv1st.h:
typedef struct s_AC SK_AC;
#include <...> /* System specific includes if required */
#include "h/skerror.h" /* Include defines for Error log base/class */
#include "h/skdebug.h" /* Include defines for debug macros */
/* Note: If sktypes.h is needed in skdrv1st.h */
/* it should be included there also (RA)*/
#define ... /* Driver Specific Definitions */
----
skdrv2nd.h:
#include "h/skrlmt.h" /* The RLMT module is mandatory */
#include "h/skvpd.h" /* other modules may be included if required */
#include "h/sk..?"
#include ".../..." /* Driver specific header files */
struct s_AC {
SK_ ...; /* Driver specific structure definitions */
SK_VPD vpd; /* Module specific structures if required */
};
#define SK_IOC ... /* Define the type of the IO context */
---
***
(3) MODULE DEPENDENCIES
=======================
Module: HwInit (skgeinit.c)
Req. Defines: SK_MAX_MACS
SK_USE_REV_DESC (required if descriptor reversal feature used)
Req. Vars: -
Req. Functions: SkPciWriteCfgWord()
Module: VPD (skvpd.c)
Req. Defines: SK_TICKS_PER_SEC
SK_MEMCPY(), SK_MEMCMP()
Req. Vars: -
Req. Functions: SkOsGetTime(), (Always)
SkPciReadCfgWord(), SkPciReadCfgDWord(), (if VPD_DO_IO)
SkPciWriteCfgWord(), SkPciWriteCfgDWord() (is not def. )
Module: ADDR (skaddr.c)
Req. Defines: SK_MAX_MACS
Req. Vars: -
Req. Functions: -
Module: HwInit (skrlmt.c)
Req. Defines: SK_MAX_MACS
Req. Types SK_MBUF
In skdrv1st.h:
typedef struct s_SkMbuf SK_MBUF;
In skdrv2nd.h:
struct s_SkMbuf {
/* Common fields */
SK_MBUF *pNext;
SK_U8 *pData; /* Data buffer. */
unsigned Size; /* Data buffer size. */
unsigned Length; /* Length of packet (<= Size). */
SK_U32 PortIdx;/* Receiving/transmitting port. */
#ifdef SK_RLMT_MBUF_PRIVATE
SK_RLMT_MBUF Rlmt; /* Private fields for RLMT. */
#endif /* SK_RLMT_MBUF_PRIVATE */
/* OS-specific fields, e.g. void *pOS; */
};
Req. Vars: -
Req. Functions: -
***
(4) DEFINE DESCRIPTION
======================
SK_BIG_ENDIAN ... must be defined if the byte order is
big endian.
File: skdrv1st.h
sample: #define SK_BIG_ENDIAN
SK_LITTLE_ENDIAN ... must be defined if the byte order is
little endian.
File: skdrv1st.h
sample: #define SK_LITTLE_ENDIAN
SK_TICKS_PER_SEC ... is defined as count of timer ticks per second.
File: skdrv1st.h
sample: #define SK_TICKS_PER_SEC SK_CONSTU64(100)
SK_MEM_MAPPED_IO ...should be defined if the driver uses
mem mapped IO.
File: skdrv1st.h
sample: #define SK_MEM_MAPPED_IO
SK_MAX_MACS ...is the maximum number of MACs supported by
the driver (per adapter).
File: skdrv1st.h
sample: #define SK_MAX_MACS 2
SK_IOC ... is the type of the IO context
It needs to be defined by every driver. For the
common sources this IoC (IO context) must be used
to access the adapter via IOs. In addition every
function which uses IOs or which calls a function
that uses IOs must have IoC in its parameter list.
(SK_IOC IoC)
Standard Library Defines
SK_MEMCMP(pDest,pSrc,N) it's like memcmp(pDest, pSrc, N)
SK_MEMCPY(pDest,pSrc,N) it's like memcpy(pDest, pSrc, N)
SK_MEMSET(pDest,Val,N) it's like memset(pDest, Val, N)
SK_STRNCPY(pDest,pSrc,N) it's like strncpy(pDest, pSrc, N)
SK_STRLEN(pSrc) it's like strlen(pSrc)
SK_STRCMP(pSrc1,pSrc2) it's like strcmp(pSrc1, pSrc2)
/* macros to accesss the adapter */
SK_IN8(IoC,Addr,pVal) ...to read a 8-bit word from the adapter's target
SK_IN16(IoC,Addr,pVal) ...to read a 16-bit word from the adapter's target
SK_IN32(IoC,Addr,pVal) ...to read a 32-bit word from the adapter's target
SK_OUT8(IoC,Addr,Val) ...to write a 8-bit word to the adapter's target
SK_OUT16(IoC,Addr,Val) ...to write a 16-bit word to the adapter's target
SK_OUT32(IoC,Addr,Val) ...to write a 32-bit word to the adapter's target
parameters: IoC IO context which is specific to the OS. IoC
must be of the type SK_IOC
Addr register offset to access
(p)Val Value or pointer to the value which should
be read or written
Note: SK_INxx and SK_OUTxx macros are also responsible
for Little- or Big Endian conversion if required.
example:
/* Define the IO context type. Usually it is the adapter's context */
#ifndef SK_IOC
#define SK_IOC SK_AC *
#endif
#ifndef SK_MEM_MAPPED_IO
#define SET_RAP(Base,Val) {\
if ((Val)>0x80) outp((unsigned)((Base)+B0_RAP), (SK_U8)((Val)>>7)); }
#define SK_IN8(pAC,Addr,pVal) { \
SET_RAP((pAC)->hw.iop, Addr); \
*(pVal) = (SK_U8) inp((unsigned)SK_ADDR((pAC)->hw.iop, Addr)); }
#define SK_OUT8(pAC,Addr,Val) { \
SET_RAP((pAC)->hw.iop, Addr); \
outp((unsigned)SK_ADDR((pAC)->hw.iop, Addr), Val); }
#else
#define SK_IN8(pAC,Addr,pVal) (*(pVal) = *((SK_U8 volatile far *) \
((pAC)->Hw.Iop + (Addr))))
#define SK_OUT8(pAC,Addr,Val) (*((SK_U8 volatile far *) \
((pAC)->Hw.Iop + (Addr))) = (Val))
#endif
usage: SK_IN8(IoC, B0_LED, &value);
SK_OUT8(IoC, B0_LED, value | LED_STAT_ON);
/* Debug Macros */
SK_DBG_PRINTF ...debug printf function
SK_DBG_CHKMOD(pAC) ...check selected sw module for debug output
SK_DBG_CHKCAT(pAC) ...check selected category for debug output
File: skdrv1st.h, if DEBUG is defined
sample: #ifdef DEBUG
#define SK_DBG_PRINTF printf
#define SK_DBG_CHKMOD(pAC) ((pAC)->DebugModules)
#define SK_DBG_CHKCAT(pAC) ((pAC)->DebugCategories)
#endif
/* How to use the DEBUG macro SK_DBG_MSG defined in skdebug.h: */
SK_DBG_MSG(pAC, Comp, Cat, Arg) Debug Macro, provides module- and category
specific debug output.
paramters: pAC pointer to adapter control structure
Comp component to debug (VPD, RLMT, os-specific..)
- values for shared sw:
area: 0x00000000 - 0x0000ffff
bits are defined in skdebug.h
- values for os-specific sw:
area: 0x00010000 - 0xffff0000
bits has TBD by os-specific sw
Cat category to debug (Init, Rx, Tx, Ctrl ...)
- values for shared sw:
area: 0x00000000 - 0x0000ffff
bits are defined in skdebug.h
- values for os-specific sw:
area: 0x00010000 - 0xffff0000
bits has TBD by os-specific sw
Arg printf argument e.g ("%d\n", len)
Arg must include braces.
Due to any restrictions of kernel printf
routines do not use other format
identifiers than: %x %d %c %s at
least in shared modules.
Combined format identifiers such
as: %lx %ld in may not be supported
by some OS specific kernel printfs.
example:
skdebug.h:
#ifdef DEBUG
/* DEBUG macro */
#define SK_DBG_MSG(pAC,Comp,Cat,Arg) \
if ((Comp) & SK_DBG_CHKMOD(pAC)) && \
((Cat) & SK_DBG_CHKCAT(pAC)) { \
SK_DEBUG_PRINTF Arg; \
}
#else /* !DEBUG */
#define SK_DBG_MSG(pAC,Comp,Cat,Arg)
#endif /* !DEGUG */
/* Error Log macro */
SK_ERR_LOG(pAc, ErrClass, ErrNum, ErrMsg) Macro to log an error
parameter: pAc Adapters context
ErrClass Error Class as defined in skerror.h
ErrNum Error Number which is module specific
The base numbers are in skerror.h
ErrMsg ASCII-Z error message.
/* Error Classes */
SK_ERRCL_OTHER Other error
SK_ERRCL_CONFIG Configuration error
SK_ERRCL_INIT Initialization error
SK_ERRCL_NORES Out of resources error
SK_ERRCL_SW internal Software error
SK_ERRCL_HW Hardware failure
SK_ERRCL_COMM Communication error
/* Error number bases */
SK_ERRBASE_RLMT Base Error number for RLMT
SK_ERRBASE_HWINIT Base Error number for HWInit
SK_ERRBASE_VPD Base Error number for VPD
SK_ERRBASE_PNMI Base Error number for PNMI
SK_ERRBASE_CSUM Base Error number for Checksum
SK_ERRBASE_SIRQ Base Error number for Special IRQ
SK_ERRBASE_I2C Base Error number for i2C module
SK_ERRBASE_QUEUE Base Error number for Scheduler
SK_ERRBASE_ADDR Base Error number for Address mod.
SK_ERRBASE_DRV Base Error number for Driver
---
skdrv1st.h:
/* os-specific DEBUG defines */
#define SK_DBGMOD_HWM 0x00010000L /* os-specific HW Module */
#ifdef DEBUG
/* modules to check Debug Module and Debug Category */
/* It is also possible to use global variables for DEBUG options */
#define SK_DBG_CHKMOD(pAC) ((pAC)->DebugModules)
#define SK_DBG_CHKCAT(pAC) ((pAC)->DebugCategories)
#endif /* !DEGUG */
---
skdrv2nd.h:
struct s_AC {
SK_U32 DebugModules; /* Bit field of modules to debug */
SK_U32 DebugCategories; /* Bit field of categories to debug */
:
:
};
---
skdriver.c
function()
{
SK_AC AC;
/* Set at very first driver initialization/configuration,
* may be changed dynamically by IOCTL ....
*/
AC.DebugModules = SK_DBGMOD_HWM | SK_DBGMOD_VPD | SK_DBG_CTRL;
AC.DebugCategories = SK_DBGCAT_CTRL;
SK_DBG_MSG(&AC, SK_DBGMOD_HWM, SK_DBGCAT_INIT|SK_DBGCAT_CTRL,
("My debug modules %x\n", AC.DebugModules));
}
***
(5) VARIABLE AND STRUCTURE DESCRIPTION
======================================
***
(6) FUNCTION DESCRIPTION
========================
SkOsGetTime()
SK_U64 SkOsGetTime(SK_AC *pAC)
Gets the current time from the system in units of SK_TICKS_PER_SEC.
This function is called by RLMT during Lookahead, which is typically
executed in the fast path during an ISR or a deferred procedure call.
returns the current time in SK_TICKS_PER_SEC
---------------------------------
int SkPciReadCfgDWord(
SK_AC *pAC, /* Adapter Control Structure Pointer */
int PciAddr, /* PCI Register Address */
SK_U32 *pVal) /* Pointer to store the read value */
Reads a 32-bit word from the adapter's configuration space.
This 32-bit word is returned in the machines endianess.
return 0: success
!=0: request failed, unable to read value
---------------------------------
int SkPciReadCfgWord(
SK_AC *pAC, /* Adapter Control Structure Pointer */
int PciAddr, /* PCI Register Address */
SK_U16 *pVal) /* Pointer to store the read value */
Reads a 16-bit word from the adapter's configuration space.
This 16-bit word is returned in the machines endianess.
return 0: success
!=0: request failed, unable to read value
---------------------------------
int SkPciReadCfgByte(
SK_AC *pAC, /* Adapter Control Structure Pointer */
int PciAddr, /* PCI Register Address */
SK_U8 *pVal) /* Pointer to store the read value */
Reads a byte from the adapter's configuration space.
return 0: success
!=0: request failed, unable to read value
---------------------------------
int SkPciWriteCfgDWord(
SK_AC *pAC, /* Adapter Control Structure Pointer */
int PciAddr, /* PCI Register Address */
SK_U32 Val) /* value to write */
Writes a 32-bit word to the adapter's configuration space.
This 32-bit word must be given in the machines endianess.
return 0: success
!=0: request failed, unable to write value
---------------------------------
int SkPciWriteCfgWord(
SK_AC *pAC, /* Adapter Control Structure Pointer */
int PciAddr, /* PCI Register Address */
SK_U16 Val) /* value to write */
Writes a 16-bit word to the adapter's configuration space.
This 16-bit word must be given in the machines endianess.
return 0: success
!=0: request failed, unable to write value
---------------------------------
int SkPciWriteCfgByte(
SK_AC *pAC, /* Adapter Control Structure Pointer */
int PciAddr, /* PCI Register Address */
SK_U8 Val) /* value to write */
Writes a byte to the adapter's configuration space.
return 0: success
!=0: request failed, unable to write value
***
(7) HISTORY
===========
$Log: ssrspec.txt,v $
Revision 1.24 1999/01/27 14:35:21 rassmann
Added requirement to SkOsGetTime().
Revision 1.23 1999/01/26 09:10:49 malthoff
Add define SK_USE_REV_DESC.
Revision 1.22 1999/01/11 12:42:53 malthoff
Modify requirements for common module.
Revision 1.21 1998/10/29 07:19:51 gklug
clarify: definition of Cfg Space functions
Revision 1.20 1998/10/19 12:56:02 rassmann
Added SK_MBUF and SK_BIG_ENDIAN.
Revision 1.19 1998/10/16 12:25:49 rassmann
Added Parameter pAC to SkOsGetTime.
Revision 1.18 1998/09/29 10:17:12 mhaveman
Added macros SK_STRNCPY(), SK_STRLEN(), and SK_STRCMP()
Revision 1.17 1998/09/28 13:28:59 malthoff
Add 'Endian comment' for SK_INxx and SK_OUTxx macro.
Revision 1.16 1998/09/16 08:25:58 cgoos
Added SK_MEMSET define for Pnmi.
Revision 1.15 1998/09/16 07:22:25 malthoff
Add macros SK_MEMCPY() and SK_MEMCMP() for VPD module.
Revision 1.14 1998/08/19 09:11:28 gklug
fix: struct are removed from c-source (see CCC)
Revision 1.13 1998/08/18 13:08:31 gklug
chg: SkOsGetTime now returns SK_U64. SK_TICKS_PER_SEC is now 64 bit, too.
Revision 1.12 1998/08/11 11:15:12 gklug
add: error classes definition
add: error bases
add: include file skerror.h
Revision 1.11 1998/08/11 09:00:21 gklug
add: Error Logging macro
Revision 1.10 1998/07/28 12:31:47 malthoff
SK_IOC must be defined without braces. We would get
Compiler error messages if we do so in prototypes and
function declarations.
Revision 1.9 1998/07/28 11:35:41 gklug
upd: spec for IoC (IO context)
Revision 1.8 1998/07/28 11:27:28 gklug
add: explanation of the usage of SK_IOC in common sources.
Revision 1.7 1998/07/23 08:32:34 malthoff
Add module dependencies for HwInit.
Add define SK_MAX_MACS.
Revision 1.6 1998/07/16 07:20:05 gklug
chg: replace \ with / in include files according to C Coding Conventions.
Revision 1.5 1998/07/14 13:54:51 gklug
Added the IO context type which is used for the IO macros.
Revision 1.4 1998/06/29 13:33:15 malthoff
Correct SK_IN and SK_OUT macros again.
It is not possible to use 'if' statements needs a ;
which is not allowed in ().
Revision 1.3 1998/06/23 11:34:29 malthoff
Correct sample SK_IN8 and SK_OUT8 macro (use ',' instead of ':')
Revision 1.2 1998/06/23 06:06:37 malthoff
Add SK_INxx() and SK_OUTxx() macros.
Add define SK_MEM_MAPPED_IO.
Revision 1.1 1998/06/19 14:05:35 malthoff
Created. Contains VPD module requirements and DEBUG macro
description. SK_INxx and SK_OUTxx macros are still missing.
*** End of Document ***
Download Driver Pack
After your driver has been downloaded, follow these simple steps to install it.
Expand the archive file (if the download file is in zip or rar format).
If the expanded file has an .exe extension, double click it and follow the installation instructions.
Otherwise, open Device Manager by right-clicking the Start menu and selecting Device Manager.
Find the device and model you want to update in the device list.
Double-click on it to open the Properties dialog box.
From the Properties dialog box, select the Driver tab.
Click the Update Driver button, then follow the instructions.
Very important: You must reboot your system to ensure that any driver updates have taken effect.
For more help, visit our Driver Support section for step-by-step videos on how to install drivers for every file type.