Snp.h 46 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032
  1. /** @file
  2. Declaration of structures and functions for SnpDxe driver.
  3. Copyright (c) 2004 - 2019, Intel Corporation. All rights reserved.<BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. **/
  6. #ifndef _SNP_H_
  7. #define _SNP_H_
  8. #include <Uefi.h>
  9. #include <Protocol/SimpleNetwork.h>
  10. #include <Protocol/PciIo.h>
  11. #include <Protocol/NetworkInterfaceIdentifier.h>
  12. #include <Protocol/DevicePath.h>
  13. #include <Guid/EventGroup.h>
  14. #include <Library/DebugLib.h>
  15. #include <Library/BaseMemoryLib.h>
  16. #include <Library/UefiDriverEntryPoint.h>
  17. #include <Library/UefiBootServicesTableLib.h>
  18. #include <Library/BaseLib.h>
  19. #include <Library/UefiLib.h>
  20. #include <Library/MemoryAllocationLib.h>
  21. #include <Library/PrintLib.h>
  22. #include <Library/PcdLib.h>
  23. #include <IndustryStandard/Pci.h>
  24. #include <IndustryStandard/Acpi.h>
  25. #define FOUR_GIGABYTES (UINT64) 0x100000000ULL
  26. #define SNP_DRIVER_SIGNATURE SIGNATURE_32 ('s', 'n', 'd', 's')
  27. #define MAX_MAP_LENGTH 100
  28. #define PCI_BAR_IO_MASK 0x00000003
  29. #define PCI_BAR_IO_MODE 0x00000001
  30. #define PCI_BAR_MEM_MASK 0x0000000F
  31. #define PCI_BAR_MEM_MODE 0x00000000
  32. #define PCI_BAR_MEM_64BIT 0x00000004
  33. #define SNP_TX_BUFFER_INCREASEMENT MAX_XMIT_BUFFERS
  34. #define SNP_MAX_TX_BUFFER_NUM 65536
  35. typedef
  36. EFI_STATUS
  37. (EFIAPI *ISSUE_UNDI32_COMMAND)(
  38. UINT64 Cdb
  39. );
  40. typedef struct {
  41. UINT32 Signature;
  42. EFI_LOCK Lock;
  43. EFI_SIMPLE_NETWORK_PROTOCOL Snp;
  44. EFI_SIMPLE_NETWORK_MODE Mode;
  45. EFI_HANDLE DeviceHandle;
  46. EFI_DEVICE_PATH_PROTOCOL *DevicePath;
  47. //
  48. // Local instance data needed by SNP driver
  49. //
  50. // Pointer to S/W UNDI API entry point
  51. // This will be NULL for H/W UNDI
  52. //
  53. ISSUE_UNDI32_COMMAND IssueUndi32Command;
  54. BOOLEAN IsSwUndi;
  55. //
  56. // undi interface number, if one undi manages more nics
  57. //
  58. PXE_IFNUM IfNum;
  59. //
  60. // Allocated tx/rx buffer that was passed to UNDI Initialize.
  61. //
  62. UINT32 TxRxBufferSize;
  63. VOID *TxRxBuffer;
  64. //
  65. // mappable buffers for receive and fill header for undi3.0
  66. // these will be used if the user buffers are above 4GB limit (instead of
  67. // mapping the user buffers)
  68. //
  69. UINT8 *ReceiveBufffer;
  70. VOID *ReceiveBufferUnmap;
  71. UINT8 *FillHeaderBuffer;
  72. VOID *FillHeaderBufferUnmap;
  73. EFI_PCI_IO_PROTOCOL *PciIo;
  74. UINT8 IoBarIndex;
  75. UINT8 MemoryBarIndex;
  76. //
  77. // Buffers for command descriptor block, command parameter block
  78. // and data block.
  79. //
  80. PXE_CDB Cdb;
  81. VOID *Cpb;
  82. VOID *CpbUnmap;
  83. VOID *Db;
  84. //
  85. // UNDI structure, we need to remember the init info for a long time!
  86. //
  87. PXE_DB_GET_INIT_INFO InitInfo;
  88. VOID *SnpDriverUnmap;
  89. //
  90. // when ever we map an address, we must remember it's address and the un-map
  91. // cookie so that we can unmap later
  92. //
  93. struct MAP_LIST {
  94. EFI_PHYSICAL_ADDRESS VirtualAddress;
  95. VOID *MapCookie;
  96. } MapList[MAX_MAP_LENGTH];
  97. EFI_EVENT ExitBootServicesEvent;
  98. //
  99. // Whether UNDI support reporting media status from GET_STATUS command,
  100. // i.e. PXE_STATFLAGS_GET_STATUS_NO_MEDIA_SUPPORTED or
  101. // PXE_STATFLAGS_GET_STATUS_NO_MEDIA_NOT_SUPPORTED
  102. //
  103. BOOLEAN MediaStatusSupported;
  104. //
  105. // Whether UNDI support cable detect for INITIALIZE command,
  106. // i.e. PXE_STATFLAGS_CABLE_DETECT_SUPPORTED or
  107. // PXE_STATFLAGS_CABLE_DETECT_NOT_SUPPORTED
  108. //
  109. BOOLEAN CableDetectSupported;
  110. //
  111. // Array of the recycled transmit buffer address from UNDI.
  112. //
  113. UINT64 *RecycledTxBuf;
  114. //
  115. // The maximum number of recycled buffer pointers in RecycledTxBuf.
  116. //
  117. UINT32 MaxRecycledTxBuf;
  118. //
  119. // Current number of recycled buffer pointers in RecycledTxBuf.
  120. //
  121. UINT32 RecycledTxBufCount;
  122. } SNP_DRIVER;
  123. #define EFI_SIMPLE_NETWORK_DEV_FROM_THIS(a) CR (a, SNP_DRIVER, Snp, SNP_DRIVER_SIGNATURE)
  124. //
  125. // Global Variables
  126. //
  127. extern EFI_DRIVER_BINDING_PROTOCOL gSimpleNetworkDriverBinding;
  128. extern EFI_COMPONENT_NAME_PROTOCOL gSimpleNetworkComponentName;
  129. extern EFI_COMPONENT_NAME2_PROTOCOL gSimpleNetworkComponentName2;
  130. /**
  131. this routine calls undi to start the interface and changes the snp state.
  132. @param Snp pointer to snp driver structure
  133. @retval EFI_DEVICE_ERROR UNDI could not be started
  134. @retval EFI_SUCCESS UNDI is started successfully
  135. **/
  136. EFI_STATUS
  137. PxeStart (
  138. IN SNP_DRIVER *Snp
  139. );
  140. /**
  141. this routine calls undi to stop the interface and changes the snp state.
  142. @param Snp pointer to snp driver structure
  143. @retval EFI_INVALID_PARAMETER invalid parameter
  144. @retval EFI_NOT_STARTED SNP is not started
  145. @retval EFI_DEVICE_ERROR SNP is not initialized
  146. @retval EFI_UNSUPPORTED operation unsupported
  147. **/
  148. EFI_STATUS
  149. PxeStop (
  150. SNP_DRIVER *Snp
  151. );
  152. /**
  153. this routine calls undi to initialize the interface.
  154. @param Snp pointer to snp driver structure
  155. @param CableDetectFlag Do/don't detect the cable (depending on what undi supports)
  156. @retval EFI_SUCCESS UNDI is initialized successfully
  157. @retval EFI_DEVICE_ERROR UNDI could not be initialized
  158. @retval Other other errors
  159. **/
  160. EFI_STATUS
  161. PxeInit (
  162. SNP_DRIVER *Snp,
  163. UINT16 CableDetectFlag
  164. );
  165. /**
  166. this routine calls undi to shut down the interface.
  167. @param Snp pointer to snp driver structure
  168. @retval EFI_SUCCESS UNDI is shut down successfully
  169. @retval EFI_DEVICE_ERROR UNDI could not be shut down
  170. **/
  171. EFI_STATUS
  172. PxeShutdown (
  173. IN SNP_DRIVER *Snp
  174. );
  175. /**
  176. this routine calls undi to read the MAC address of the NIC and updates the
  177. mode structure with the address.
  178. @param Snp pointer to snp driver structure.
  179. @retval EFI_SUCCESS the MAC address of the NIC is read successfully.
  180. @retval EFI_DEVICE_ERROR failed to read the MAC address of the NIC.
  181. **/
  182. EFI_STATUS
  183. PxeGetStnAddr (
  184. SNP_DRIVER *Snp
  185. );
  186. /**
  187. Call undi to get the status of the interrupts, get the list of recycled transmit
  188. buffers that completed transmitting. The recycled transmit buffer address will
  189. be saved into Snp->RecycledTxBuf. This function will also update the MediaPresent
  190. field of EFI_SIMPLE_NETWORK_MODE if UNDI support it.
  191. @param[in] Snp Pointer to snp driver structure.
  192. @param[out] InterruptStatusPtr A non null pointer to contain the interrupt
  193. status.
  194. @param[in] GetTransmittedBuf Set to TRUE to retrieve the recycled transmit
  195. buffer address.
  196. @retval EFI_SUCCESS The status of the network interface was retrieved.
  197. @retval EFI_DEVICE_ERROR The command could not be sent to the network
  198. interface.
  199. **/
  200. EFI_STATUS
  201. PxeGetStatus (
  202. IN SNP_DRIVER *Snp,
  203. OUT UINT32 *InterruptStatusPtr,
  204. IN BOOLEAN GetTransmittedBuf
  205. );
  206. /**
  207. This is a callback routine supplied to UNDI3.1 at undi_start time.
  208. UNDI call this routine when it wants to have exclusive access to a critical
  209. section of the code/data.
  210. New callbacks for 3.1:
  211. there won't be a virtual2physical callback for UNDI 3.1 because undi3.1 uses
  212. the MemMap call to map the required address by itself!
  213. @param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this to
  214. store Undi interface context (Undi does not read or write
  215. this variable)
  216. @param Enable non-zero indicates acquire
  217. zero indicates release
  218. **/
  219. VOID
  220. EFIAPI
  221. SnpUndi32CallbackBlock (
  222. IN UINT64 UniqueId,
  223. IN UINT32 Enable
  224. );
  225. /**
  226. This is a callback routine supplied to UNDI at undi_start time.
  227. UNDI call this routine with the number of micro seconds when it wants to
  228. pause.
  229. @param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this to
  230. store Undi interface context (Undi does not read or write
  231. this variable)
  232. @param MicroSeconds number of micro seconds to pause, usually multiple of 10.
  233. **/
  234. VOID
  235. EFIAPI
  236. SnpUndi32CallbackDelay (
  237. IN UINT64 UniqueId,
  238. IN UINT64 MicroSeconds
  239. );
  240. /**
  241. This is a callback routine supplied to UNDI at undi_start time.
  242. This is the IO routine for UNDI3.1 to start CPB.
  243. @param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this
  244. to store Undi interface context (Undi does not read or
  245. write this variable)
  246. @param ReadOrWrite indicates read or write, IO or Memory.
  247. @param NumBytes number of bytes to read or write.
  248. @param MemOrPortAddr IO or memory address to read from or write to.
  249. @param BufferPtr memory location to read into or that contains the bytes
  250. to write.
  251. **/
  252. VOID
  253. EFIAPI
  254. SnpUndi32CallbackMemio (
  255. IN UINT64 UniqueId,
  256. IN UINT8 ReadOrWrite,
  257. IN UINT8 NumBytes,
  258. IN UINT64 MemOrPortAddr,
  259. IN OUT UINT64 BufferPtr
  260. );
  261. /**
  262. This is a callback routine supplied to UNDI at undi_start time.
  263. UNDI call this routine when it has to map a CPU address to a device
  264. address.
  265. @param UniqueId - This was supplied to UNDI at Undi_Start, SNP uses this to store
  266. Undi interface context (Undi does not read or write this variable)
  267. @param CpuAddr - Virtual address to be mapped!
  268. @param NumBytes - size of memory to be mapped
  269. @param Direction - direction of data flow for this memory's usage:
  270. cpu->device, device->cpu or both ways
  271. @param DeviceAddrPtr - pointer to return the mapped device address
  272. **/
  273. VOID
  274. EFIAPI
  275. SnpUndi32CallbackMap (
  276. IN UINT64 UniqueId,
  277. IN UINT64 CpuAddr,
  278. IN UINT32 NumBytes,
  279. IN UINT32 Direction,
  280. IN OUT UINT64 DeviceAddrPtr
  281. );
  282. /**
  283. This is a callback routine supplied to UNDI at undi_start time.
  284. UNDI call this routine when it wants to unmap an address that was previously
  285. mapped using map callback.
  286. @param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this to store.
  287. Undi interface context (Undi does not read or write this variable)
  288. @param CpuAddr Virtual address that was mapped!
  289. @param NumBytes size of memory mapped
  290. @param Direction direction of data flow for this memory's usage:
  291. cpu->device, device->cpu or both ways
  292. @param DeviceAddr the mapped device address
  293. **/
  294. VOID
  295. EFIAPI
  296. SnpUndi32CallbackUnmap (
  297. IN UINT64 UniqueId,
  298. IN UINT64 CpuAddr,
  299. IN UINT32 NumBytes,
  300. IN UINT32 Direction,
  301. IN UINT64 DeviceAddr
  302. );
  303. /**
  304. This is a callback routine supplied to UNDI at undi_start time.
  305. UNDI call this routine when it wants synchronize the virtual buffer contents
  306. with the mapped buffer contents. The virtual and mapped buffers need not
  307. correspond to the same physical memory (especially if the virtual address is
  308. > 4GB). Depending on the direction for which the buffer is mapped, undi will
  309. need to synchronize their contents whenever it writes to/reads from the buffer
  310. using either the cpu address or the device address.
  311. EFI does not provide a sync call, since virt=physical, we should just do
  312. the synchronization ourself here!
  313. @param UniqueId This was supplied to UNDI at Undi_Start, SNP uses this to store
  314. Undi interface context (Undi does not read or write this variable)
  315. @param CpuAddr Virtual address that was mapped!
  316. @param NumBytes size of memory mapped.
  317. @param Direction direction of data flow for this memory's usage:
  318. cpu->device, device->cpu or both ways.
  319. @param DeviceAddr the mapped device address.
  320. **/
  321. VOID
  322. EFIAPI
  323. SnpUndi32CallbackSync (
  324. IN UINT64 UniqueId,
  325. IN UINT64 CpuAddr,
  326. IN UINT32 NumBytes,
  327. IN UINT32 Direction,
  328. IN UINT64 DeviceAddr
  329. );
  330. /**
  331. Changes the state of a network interface from "stopped" to "started".
  332. This function starts a network interface. If the network interface successfully
  333. starts, then EFI_SUCCESS will be returned.
  334. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  335. @retval EFI_SUCCESS The network interface was started.
  336. @retval EFI_ALREADY_STARTED The network interface is already in the started state.
  337. @retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
  338. EFI_SIMPLE_NETWORK_PROTOCOL structure.
  339. @retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
  340. @retval EFI_UNSUPPORTED This function is not supported by the network interface.
  341. **/
  342. EFI_STATUS
  343. EFIAPI
  344. SnpUndi32Start (
  345. IN EFI_SIMPLE_NETWORK_PROTOCOL *This
  346. );
  347. /**
  348. Changes the state of a network interface from "started" to "stopped".
  349. This function stops a network interface. This call is only valid if the network
  350. interface is in the started state. If the network interface was successfully
  351. stopped, then EFI_SUCCESS will be returned.
  352. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  353. @retval EFI_SUCCESS The network interface was stopped.
  354. @retval EFI_NOT_STARTED The network interface has not been started.
  355. @retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
  356. EFI_SIMPLE_NETWORK_PROTOCOL structure.
  357. @retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
  358. @retval EFI_UNSUPPORTED This function is not supported by the network interface.
  359. **/
  360. EFI_STATUS
  361. EFIAPI
  362. SnpUndi32Stop (
  363. IN EFI_SIMPLE_NETWORK_PROTOCOL *This
  364. );
  365. /**
  366. Resets a network adapter and allocates the transmit and receive buffers
  367. required by the network interface; optionally, also requests allocation of
  368. additional transmit and receive buffers.
  369. This function allocates the transmit and receive buffers required by the network
  370. interface. If this allocation fails, then EFI_OUT_OF_RESOURCES is returned.
  371. If the allocation succeeds and the network interface is successfully initialized,
  372. then EFI_SUCCESS will be returned.
  373. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  374. @param ExtraRxBufferSize The size, in bytes, of the extra receive buffer space
  375. that the driver should allocate for the network interface.
  376. Some network interfaces will not be able to use the
  377. extra buffer, and the caller will not know if it is
  378. actually being used.
  379. @param ExtraTxBufferSize The size, in bytes, of the extra transmit buffer space
  380. that the driver should allocate for the network interface.
  381. Some network interfaces will not be able to use the
  382. extra buffer, and the caller will not know if it is
  383. actually being used.
  384. @retval EFI_SUCCESS The network interface was initialized.
  385. @retval EFI_NOT_STARTED The network interface has not been started.
  386. @retval EFI_OUT_OF_RESOURCES There was not enough memory for the transmit and
  387. receive buffers.
  388. @retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
  389. EFI_SIMPLE_NETWORK_PROTOCOL structure.
  390. @retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
  391. @retval EFI_UNSUPPORTED The increased buffer size feature is not supported.
  392. **/
  393. EFI_STATUS
  394. EFIAPI
  395. SnpUndi32Initialize (
  396. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  397. IN UINTN ExtraRxBufferSize OPTIONAL,
  398. IN UINTN ExtraTxBufferSize OPTIONAL
  399. );
  400. /**
  401. Resets a network adapter and reinitializes it with the parameters that were
  402. provided in the previous call to Initialize().
  403. This function resets a network adapter and reinitializes it with the parameters
  404. that were provided in the previous call to Initialize(). The transmit and
  405. receive queues are emptied and all pending interrupts are cleared.
  406. Receive filters, the station address, the statistics, and the multicast-IP-to-HW
  407. MAC addresses are not reset by this call. If the network interface was
  408. successfully reset, then EFI_SUCCESS will be returned. If the driver has not
  409. been initialized, EFI_DEVICE_ERROR will be returned.
  410. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  411. @param ExtendedVerification Indicates that the driver may perform a more
  412. exhaustive verification operation of the device
  413. during reset.
  414. @retval EFI_SUCCESS The network interface was reset.
  415. @retval EFI_NOT_STARTED The network interface has not been started.
  416. @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value.
  417. @retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
  418. @retval EFI_UNSUPPORTED This function is not supported by the network interface.
  419. **/
  420. EFI_STATUS
  421. EFIAPI
  422. SnpUndi32Reset (
  423. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  424. IN BOOLEAN ExtendedVerification
  425. );
  426. /**
  427. Resets a network adapter and leaves it in a state that is safe for another
  428. driver to initialize.
  429. This function releases the memory buffers assigned in the Initialize() call.
  430. Pending transmits and receives are lost, and interrupts are cleared and disabled.
  431. After this call, only the Initialize() and Stop() calls may be used. If the
  432. network interface was successfully shutdown, then EFI_SUCCESS will be returned.
  433. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
  434. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  435. @retval EFI_SUCCESS The network interface was shutdown.
  436. @retval EFI_NOT_STARTED The network interface has not been started.
  437. @retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
  438. EFI_SIMPLE_NETWORK_PROTOCOL structure.
  439. @retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
  440. **/
  441. EFI_STATUS
  442. EFIAPI
  443. SnpUndi32Shutdown (
  444. IN EFI_SIMPLE_NETWORK_PROTOCOL *This
  445. );
  446. /**
  447. Manages the multicast receive filters of a network interface.
  448. This function is used enable and disable the hardware and software receive
  449. filters for the underlying network device.
  450. The receive filter change is broken down into three steps:
  451. * The filter mask bits that are set (ON) in the Enable parameter are added to
  452. the current receive filter settings.
  453. * The filter mask bits that are set (ON) in the Disable parameter are subtracted
  454. from the updated receive filter settings.
  455. * If the resulting receive filter setting is not supported by the hardware a
  456. more liberal setting is selected.
  457. If the same bits are set in the Enable and Disable parameters, then the bits
  458. in the Disable parameter takes precedence.
  459. If the ResetMCastFilter parameter is TRUE, then the multicast address list
  460. filter is disabled (irregardless of what other multicast bits are set in the
  461. Enable and Disable parameters). The SNP->Mode->MCastFilterCount field is set
  462. to zero. The Snp->Mode->MCastFilter contents are undefined.
  463. After enabling or disabling receive filter settings, software should verify
  464. the new settings by checking the Snp->Mode->ReceiveFilterSettings,
  465. Snp->Mode->MCastFilterCount and Snp->Mode->MCastFilter fields.
  466. Note: Some network drivers and/or devices will automatically promote receive
  467. filter settings if the requested setting can not be honored. For example, if
  468. a request for four multicast addresses is made and the underlying hardware
  469. only supports two multicast addresses the driver might set the promiscuous
  470. or promiscuous multicast receive filters instead. The receiving software is
  471. responsible for discarding any extra packets that get through the hardware
  472. receive filters.
  473. Note: Note: To disable all receive filter hardware, the network driver must
  474. be Shutdown() and Stopped(). Calling ReceiveFilters() with Disable set to
  475. Snp->Mode->ReceiveFilterSettings will make it so no more packets are
  476. returned by the Receive() function, but the receive hardware may still be
  477. moving packets into system memory before inspecting and discarding them.
  478. Unexpected system errors, reboots and hangs can occur if an OS is loaded
  479. and the network devices are not Shutdown() and Stopped().
  480. If ResetMCastFilter is TRUE, then the multicast receive filter list on the
  481. network interface will be reset to the default multicast receive filter list.
  482. If ResetMCastFilter is FALSE, and this network interface allows the multicast
  483. receive filter list to be modified, then the MCastFilterCnt and MCastFilter
  484. are used to update the current multicast receive filter list. The modified
  485. receive filter list settings can be found in the MCastFilter field of
  486. EFI_SIMPLE_NETWORK_MODE. If the network interface does not allow the multicast
  487. receive filter list to be modified, then EFI_INVALID_PARAMETER will be returned.
  488. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
  489. If the receive filter mask and multicast receive filter list have been
  490. successfully updated on the network interface, EFI_SUCCESS will be returned.
  491. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  492. @param Enable A bit mask of receive filters to enable on the network
  493. interface.
  494. @param Disable A bit mask of receive filters to disable on the network
  495. interface. For backward compatibility with EFI 1.1
  496. platforms, the EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit
  497. must be set when the ResetMCastFilter parameter is TRUE.
  498. @param ResetMCastFilter Set to TRUE to reset the contents of the multicast
  499. receive filters on the network interface to their
  500. default values.
  501. @param MCastFilterCnt Number of multicast HW MAC addresses in the new MCastFilter
  502. list. This value must be less than or equal to the
  503. MCastFilterCnt field of EFI_SIMPLE_NETWORK_MODE.
  504. This field is optional if ResetMCastFilter is TRUE.
  505. @param MCastFilter A pointer to a list of new multicast receive filter HW
  506. MAC addresses. This list will replace any existing
  507. multicast HW MAC address list. This field is optional
  508. if ResetMCastFilter is TRUE.
  509. @retval EFI_SUCCESS The multicast receive filter list was updated.
  510. @retval EFI_NOT_STARTED The network interface has not been started.
  511. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
  512. * This is NULL
  513. * There are bits set in Enable that are not set
  514. in Snp->Mode->ReceiveFilterMask
  515. * There are bits set in Disable that are not set
  516. in Snp->Mode->ReceiveFilterMask
  517. * Multicast is being enabled (the
  518. EFI_SIMPLE_NETWORK_RECEIVE_MULTICAST bit is
  519. set in Enable, it is not set in Disable, and
  520. ResetMCastFilter is FALSE) and MCastFilterCount
  521. is zero
  522. * Multicast is being enabled and MCastFilterCount
  523. is greater than Snp->Mode->MaxMCastFilterCount
  524. * Multicast is being enabled and MCastFilter is NULL
  525. * Multicast is being enabled and one or more of
  526. the addresses in the MCastFilter list are not
  527. valid multicast MAC addresses
  528. @retval EFI_DEVICE_ERROR One or more of the following conditions is TRUE:
  529. * The network interface has been started but has
  530. not been initialized
  531. * An unexpected error was returned by the
  532. underlying network driver or device
  533. @retval EFI_UNSUPPORTED This function is not supported by the network
  534. interface.
  535. **/
  536. EFI_STATUS
  537. EFIAPI
  538. SnpUndi32ReceiveFilters (
  539. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  540. IN UINT32 Enable,
  541. IN UINT32 Disable,
  542. IN BOOLEAN ResetMCastFilter,
  543. IN UINTN MCastFilterCnt OPTIONAL,
  544. IN EFI_MAC_ADDRESS *MCastFilter OPTIONAL
  545. );
  546. /**
  547. Modifies or resets the current station address, if supported.
  548. This function modifies or resets the current station address of a network
  549. interface, if supported. If Reset is TRUE, then the current station address is
  550. set to the network interface's permanent address. If Reset is FALSE, and the
  551. network interface allows its station address to be modified, then the current
  552. station address is changed to the address specified by New. If the network
  553. interface does not allow its station address to be modified, then
  554. EFI_INVALID_PARAMETER will be returned. If the station address is successfully
  555. updated on the network interface, EFI_SUCCESS will be returned. If the driver
  556. has not been initialized, EFI_DEVICE_ERROR will be returned.
  557. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  558. @param Reset Flag used to reset the station address to the network interface's
  559. permanent address.
  560. @param New New station address to be used for the network interface.
  561. @retval EFI_SUCCESS The network interface's station address was updated.
  562. @retval EFI_NOT_STARTED The Simple Network Protocol interface has not been
  563. started by calling Start().
  564. @retval EFI_INVALID_PARAMETER The New station address was not accepted by the NIC.
  565. @retval EFI_INVALID_PARAMETER Reset is FALSE and New is NULL.
  566. @retval EFI_DEVICE_ERROR The Simple Network Protocol interface has not
  567. been initialized by calling Initialize().
  568. @retval EFI_DEVICE_ERROR An error occurred attempting to set the new
  569. station address.
  570. @retval EFI_UNSUPPORTED The NIC does not support changing the network
  571. interface's station address.
  572. **/
  573. EFI_STATUS
  574. EFIAPI
  575. SnpUndi32StationAddress (
  576. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  577. IN BOOLEAN Reset,
  578. IN EFI_MAC_ADDRESS *New OPTIONAL
  579. );
  580. /**
  581. Resets or collects the statistics on a network interface.
  582. This function resets or collects the statistics on a network interface. If the
  583. size of the statistics table specified by StatisticsSize is not big enough for
  584. all the statistics that are collected by the network interface, then a partial
  585. buffer of statistics is returned in StatisticsTable, StatisticsSize is set to
  586. the size required to collect all the available statistics, and
  587. EFI_BUFFER_TOO_SMALL is returned.
  588. If StatisticsSize is big enough for all the statistics, then StatisticsTable
  589. will be filled, StatisticsSize will be set to the size of the returned
  590. StatisticsTable structure, and EFI_SUCCESS is returned.
  591. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
  592. If Reset is FALSE, and both StatisticsSize and StatisticsTable are NULL, then
  593. no operations will be performed, and EFI_SUCCESS will be returned.
  594. If Reset is TRUE, then all of the supported statistics counters on this network
  595. interface will be reset to zero.
  596. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  597. @param Reset Set to TRUE to reset the statistics for the network interface.
  598. @param StatisticsSize On input the size, in bytes, of StatisticsTable. On output
  599. the size, in bytes, of the resulting table of statistics.
  600. @param StatisticsTable A pointer to the EFI_NETWORK_STATISTICS structure that
  601. contains the statistics. Type EFI_NETWORK_STATISTICS is
  602. defined in "Related Definitions" below.
  603. @retval EFI_SUCCESS The requested operation succeeded.
  604. @retval EFI_NOT_STARTED The Simple Network Protocol interface has not been
  605. started by calling Start().
  606. @retval EFI_BUFFER_TOO_SMALL StatisticsSize is not NULL and StatisticsTable is
  607. NULL. The current buffer size that is needed to
  608. hold all the statistics is returned in StatisticsSize.
  609. @retval EFI_BUFFER_TOO_SMALL StatisticsSize is not NULL and StatisticsTable is
  610. not NULL. The current buffer size that is needed
  611. to hold all the statistics is returned in
  612. StatisticsSize. A partial set of statistics is
  613. returned in StatisticsTable.
  614. @retval EFI_INVALID_PARAMETER StatisticsSize is NULL and StatisticsTable is not
  615. NULL.
  616. @retval EFI_DEVICE_ERROR The Simple Network Protocol interface has not
  617. been initialized by calling Initialize().
  618. @retval EFI_DEVICE_ERROR An error was encountered collecting statistics
  619. from the NIC.
  620. @retval EFI_UNSUPPORTED The NIC does not support collecting statistics
  621. from the network interface.
  622. **/
  623. EFI_STATUS
  624. EFIAPI
  625. SnpUndi32Statistics (
  626. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  627. IN BOOLEAN Reset,
  628. IN OUT UINTN *StatisticsSize OPTIONAL,
  629. IN OUT EFI_NETWORK_STATISTICS *StatisticsTable OPTIONAL
  630. );
  631. /**
  632. Converts a multicast IP address to a multicast HW MAC address.
  633. This function converts a multicast IP address to a multicast HW MAC address
  634. for all packet transactions. If the mapping is accepted, then EFI_SUCCESS will
  635. be returned.
  636. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  637. @param IPv6 Set to TRUE if the multicast IP address is IPv6 [RFC 2460].
  638. Set to FALSE if the multicast IP address is IPv4 [RFC 791].
  639. @param IP The multicast IP address that is to be converted to a multicast
  640. HW MAC address.
  641. @param MAC The multicast HW MAC address that is to be generated from IP.
  642. @retval EFI_SUCCESS The multicast IP address was mapped to the
  643. multicast HW MAC address.
  644. @retval EFI_NOT_STARTED The Simple Network Protocol interface has not
  645. been started by calling Start().
  646. @retval EFI_INVALID_PARAMETER IP is NULL.
  647. @retval EFI_INVALID_PARAMETER MAC is NULL.
  648. @retval EFI_INVALID_PARAMETER IP does not point to a valid IPv4 or IPv6
  649. multicast address.
  650. @retval EFI_DEVICE_ERROR The Simple Network Protocol interface has not
  651. been initialized by calling Initialize().
  652. @retval EFI_UNSUPPORTED IPv6 is TRUE and the implementation does not
  653. support IPv6 multicast to MAC address conversion.
  654. **/
  655. EFI_STATUS
  656. EFIAPI
  657. SnpUndi32McastIpToMac (
  658. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  659. IN BOOLEAN IPv6,
  660. IN EFI_IP_ADDRESS *IP,
  661. OUT EFI_MAC_ADDRESS *MAC
  662. );
  663. /**
  664. Performs read and write operations on the NVRAM device attached to a network
  665. interface.
  666. This function performs read and write operations on the NVRAM device attached
  667. to a network interface. If ReadWrite is TRUE, a read operation is performed.
  668. If ReadWrite is FALSE, a write operation is performed. Offset specifies the
  669. byte offset at which to start either operation. Offset must be a multiple of
  670. NvRamAccessSize , and it must have a value between zero and NvRamSize.
  671. BufferSize specifies the length of the read or write operation. BufferSize must
  672. also be a multiple of NvRamAccessSize, and Offset + BufferSize must not exceed
  673. NvRamSize.
  674. If any of the above conditions is not met, then EFI_INVALID_PARAMETER will be
  675. returned.
  676. If all the conditions are met and the operation is "read," the NVRAM device
  677. attached to the network interface will be read into Buffer and EFI_SUCCESS
  678. will be returned. If this is a write operation, the contents of Buffer will be
  679. used to update the contents of the NVRAM device attached to the network
  680. interface and EFI_SUCCESS will be returned.
  681. It does the basic checking on the input parameters and retrieves snp structure
  682. and then calls the read_nvdata() call which does the actual reading
  683. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  684. @param ReadWrite TRUE for read operations, FALSE for write operations.
  685. @param Offset Byte offset in the NVRAM device at which to start the read or
  686. write operation. This must be a multiple of NvRamAccessSize
  687. and less than NvRamSize. (See EFI_SIMPLE_NETWORK_MODE)
  688. @param BufferSize The number of bytes to read or write from the NVRAM device.
  689. This must also be a multiple of NvramAccessSize.
  690. @param Buffer A pointer to the data buffer.
  691. @retval EFI_SUCCESS The NVRAM access was performed.
  692. @retval EFI_NOT_STARTED The network interface has not been started.
  693. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
  694. * The This parameter is NULL
  695. * The This parameter does not point to a valid
  696. EFI_SIMPLE_NETWORK_PROTOCOL structure
  697. * The Offset parameter is not a multiple of
  698. EFI_SIMPLE_NETWORK_MODE.NvRamAccessSize
  699. * The Offset parameter is not less than
  700. EFI_SIMPLE_NETWORK_MODE.NvRamSize
  701. * The BufferSize parameter is not a multiple of
  702. EFI_SIMPLE_NETWORK_MODE.NvRamAccessSize
  703. * The Buffer parameter is NULL
  704. @retval EFI_DEVICE_ERROR The command could not be sent to the network
  705. interface.
  706. @retval EFI_UNSUPPORTED This function is not supported by the network
  707. interface.
  708. **/
  709. EFI_STATUS
  710. EFIAPI
  711. SnpUndi32NvData (
  712. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  713. IN BOOLEAN ReadWrite,
  714. IN UINTN Offset,
  715. IN UINTN BufferSize,
  716. IN OUT VOID *Buffer
  717. );
  718. /**
  719. Reads the current interrupt status and recycled transmit buffer status from a
  720. network interface.
  721. This function gets the current interrupt and recycled transmit buffer status
  722. from the network interface. The interrupt status is returned as a bit mask in
  723. InterruptStatus. If InterruptStatus is NULL, the interrupt status will not be
  724. read. If TxBuf is not NULL, a recycled transmit buffer address will be retrieved.
  725. If a recycled transmit buffer address is returned in TxBuf, then the buffer has
  726. been successfully transmitted, and the status for that buffer is cleared. If
  727. the status of the network interface is successfully collected, EFI_SUCCESS
  728. will be returned. If the driver has not been initialized, EFI_DEVICE_ERROR will
  729. be returned.
  730. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  731. @param InterruptStatus A pointer to the bit mask of the currently active
  732. interrupts (see "Related Definitions"). If this is NULL,
  733. the interrupt status will not be read from the device.
  734. If this is not NULL, the interrupt status will be read
  735. from the device. When the interrupt status is read, it
  736. will also be cleared. Clearing the transmit interrupt does
  737. not empty the recycled transmit buffer array.
  738. @param TxBuf Recycled transmit buffer address. The network interface
  739. will not transmit if its internal recycled transmit
  740. buffer array is full. Reading the transmit buffer does
  741. not clear the transmit interrupt. If this is NULL, then
  742. the transmit buffer status will not be read. If there
  743. are no transmit buffers to recycle and TxBuf is not NULL,
  744. TxBuf will be set to NULL.
  745. @retval EFI_SUCCESS The status of the network interface was retrieved.
  746. @retval EFI_NOT_STARTED The network interface has not been started.
  747. @retval EFI_INVALID_PARAMETER This parameter was NULL or did not point to a valid
  748. EFI_SIMPLE_NETWORK_PROTOCOL structure.
  749. @retval EFI_DEVICE_ERROR The command could not be sent to the network
  750. interface.
  751. **/
  752. EFI_STATUS
  753. EFIAPI
  754. SnpUndi32GetStatus (
  755. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  756. OUT UINT32 *InterruptStatus OPTIONAL,
  757. OUT VOID **TxBuf OPTIONAL
  758. );
  759. /**
  760. Places a packet in the transmit queue of a network interface.
  761. This function places the packet specified by Header and Buffer on the transmit
  762. queue. If HeaderSize is nonzero and HeaderSize is not equal to
  763. This->Mode->MediaHeaderSize, then EFI_INVALID_PARAMETER will be returned. If
  764. BufferSize is less than This->Mode->MediaHeaderSize, then EFI_BUFFER_TOO_SMALL
  765. will be returned. If Buffer is NULL, then EFI_INVALID_PARAMETER will be
  766. returned. If HeaderSize is nonzero and DestAddr or Protocol is NULL, then
  767. EFI_INVALID_PARAMETER will be returned. If the transmit engine of the network
  768. interface is busy, then EFI_NOT_READY will be returned. If this packet can be
  769. accepted by the transmit engine of the network interface, the packet contents
  770. specified by Buffer will be placed on the transmit queue of the network
  771. interface, and EFI_SUCCESS will be returned. GetStatus() can be used to
  772. determine when the packet has actually been transmitted. The contents of the
  773. Buffer must not be modified until the packet has actually been transmitted.
  774. The Transmit() function performs nonblocking I/O. A caller who wants to perform
  775. blocking I/O, should call Transmit(), and then GetStatus() until the
  776. transmitted buffer shows up in the recycled transmit buffer.
  777. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
  778. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  779. @param HeaderSize The size, in bytes, of the media header to be filled in by the
  780. Transmit() function. If HeaderSize is nonzero, then it must
  781. be equal to This->Mode->MediaHeaderSize and the DestAddr and
  782. Protocol parameters must not be NULL.
  783. @param BufferSize The size, in bytes, of the entire packet (media header and
  784. data) to be transmitted through the network interface.
  785. @param Buffer A pointer to the packet (media header followed by data) to be
  786. transmitted. This parameter cannot be NULL. If HeaderSize is
  787. zero, then the media header in Buffer must already be filled
  788. in by the caller. If HeaderSize is nonzero, then the media
  789. header will be filled in by the Transmit() function.
  790. @param SrcAddr The source HW MAC address. If HeaderSize is zero, then this
  791. parameter is ignored. If HeaderSize is nonzero and SrcAddr
  792. is NULL, then This->Mode->CurrentAddress is used for the
  793. source HW MAC address.
  794. @param DestAddr The destination HW MAC address. If HeaderSize is zero, then
  795. this parameter is ignored.
  796. @param Protocol The type of header to build. If HeaderSize is zero, then this
  797. parameter is ignored. See RFC 1700, section "Ether Types,"
  798. for examples.
  799. @retval EFI_SUCCESS The packet was placed on the transmit queue.
  800. @retval EFI_NOT_STARTED The network interface has not been started.
  801. @retval EFI_NOT_READY The network interface is too busy to accept this
  802. transmit request.
  803. @retval EFI_BUFFER_TOO_SMALL The BufferSize parameter is too small.
  804. @retval EFI_INVALID_PARAMETER One or more of the parameters has an unsupported
  805. value.
  806. @retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
  807. @retval EFI_UNSUPPORTED This function is not supported by the network interface.
  808. **/
  809. EFI_STATUS
  810. EFIAPI
  811. SnpUndi32Transmit (
  812. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  813. IN UINTN HeaderSize,
  814. IN UINTN BufferSize,
  815. IN VOID *Buffer,
  816. IN EFI_MAC_ADDRESS *SrcAddr OPTIONAL,
  817. IN EFI_MAC_ADDRESS *DestAddr OPTIONAL,
  818. IN UINT16 *Protocol OPTIONAL
  819. );
  820. /**
  821. Receives a packet from a network interface.
  822. This function retrieves one packet from the receive queue of a network interface.
  823. If there are no packets on the receive queue, then EFI_NOT_READY will be
  824. returned. If there is a packet on the receive queue, and the size of the packet
  825. is smaller than BufferSize, then the contents of the packet will be placed in
  826. Buffer, and BufferSize will be updated with the actual size of the packet.
  827. In addition, if SrcAddr, DestAddr, and Protocol are not NULL, then these values
  828. will be extracted from the media header and returned. EFI_SUCCESS will be
  829. returned if a packet was successfully received.
  830. If BufferSize is smaller than the received packet, then the size of the receive
  831. packet will be placed in BufferSize and EFI_BUFFER_TOO_SMALL will be returned.
  832. If the driver has not been initialized, EFI_DEVICE_ERROR will be returned.
  833. @param This A pointer to the EFI_SIMPLE_NETWORK_PROTOCOL instance.
  834. @param HeaderSize The size, in bytes, of the media header received on the network
  835. interface. If this parameter is NULL, then the media header size
  836. will not be returned.
  837. @param BufferSize On entry, the size, in bytes, of Buffer. On exit, the size, in
  838. bytes, of the packet that was received on the network interface.
  839. @param Buffer A pointer to the data buffer to receive both the media
  840. header and the data.
  841. @param SrcAddr The source HW MAC address. If this parameter is NULL, the HW
  842. MAC source address will not be extracted from the media header.
  843. @param DestAddr The destination HW MAC address. If this parameter is NULL,
  844. the HW MAC destination address will not be extracted from
  845. the media header.
  846. @param Protocol The media header type. If this parameter is NULL, then the
  847. protocol will not be extracted from the media header. See
  848. RFC 1700 section "Ether Types" for examples.
  849. @retval EFI_SUCCESS The received data was stored in Buffer, and
  850. BufferSize has been updated to the number of
  851. bytes received.
  852. @retval EFI_NOT_STARTED The network interface has not been started.
  853. @retval EFI_NOT_READY No packets have been received on the network interface.
  854. @retval EFI_BUFFER_TOO_SMALL BufferSize is too small for the received packets.
  855. BufferSize has been updated to the required size.
  856. @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
  857. * The This parameter is NULL
  858. * The This parameter does not point to a valid
  859. EFI_SIMPLE_NETWORK_PROTOCOL structure.
  860. * The BufferSize parameter is NULL
  861. * The Buffer parameter is NULL
  862. @retval EFI_DEVICE_ERROR The command could not be sent to the network interface.
  863. **/
  864. EFI_STATUS
  865. EFIAPI
  866. SnpUndi32Receive (
  867. IN EFI_SIMPLE_NETWORK_PROTOCOL *This,
  868. OUT UINTN *HeaderSize OPTIONAL,
  869. IN OUT UINTN *BufferSize,
  870. OUT VOID *Buffer,
  871. OUT EFI_MAC_ADDRESS *SrcAddr OPTIONAL,
  872. OUT EFI_MAC_ADDRESS *DestAddr OPTIONAL,
  873. OUT UINT16 *Protocol OPTIONAL
  874. );
  875. /**
  876. Notification call back function for WaitForPacket event.
  877. @param Event EFI Event.
  878. @param SnpPtr Pointer to SNP_DRIVER structure.
  879. **/
  880. VOID
  881. EFIAPI
  882. SnpWaitForPacketNotify (
  883. EFI_EVENT Event,
  884. VOID *SnpPtr
  885. );
  886. #define SNP_MEM_PAGES(x) (((x) - 1) / 4096 + 1)
  887. #endif /* _SNP_H_ */