bind() : set local socket address¶

Sockets that receive incoming request packets will bind to a local address,using thebind() syscall.

structsockaddr_mctpaddr;addr.smctp_family=AF_MCTP;addr.smctp_network=MCTP_NET_ANY;addr.smctp_addr.s_addr=MCTP_ADDR_ANY;addr.smctp_type=MCTP_TYPE_PLDM;addr.smctp_tag=MCTP_TAG_OWNER;intrc=bind(sd,(structsockaddr*)&addr,sizeof(addr));

This establishes the local address of the socket. Incoming MCTP messages thatmatch the network, address, and message type will be received by this socket.The reference to ‘incoming’ is important here; a bound socket will only receivemessages with the TO bit set, to indicate an incoming request message, ratherthan a response.

Thesmctp_tag value will configure the tags accepted from the remote side ofthis socket. Given the above, the only valid value isMCTP_TAG_OWNER, whichwill result in remotely “owned” tags being routed to this socket. SinceMCTP_TAG_OWNER is set, the 3 least-significant bits ofsmctp_tag are notused; callers must set them to zero.

Asmctp_network value ofMCTP_NET_ANY will configure the socket toreceive incoming packets from any locally-connected network. A specific networkvalue will cause the socket to only receive incoming messages from that network.

Thesmctp_addr field specifies a local address to bind to. A value ofMCTP_ADDR_ANY configures the socket to receive messages addressed to anylocal destination EID.

Thesmctp_type field specifies which message types to receive. Only thelower 7 bits of the type is matched on incoming messages (ie., themost-significant IC bit is not part of the match). This results in the socketreceiving packets with and without a message integrity check footer.

sendto(),sendmsg(),send() : transmit an MCTP message¶

An MCTP message is transmitted using one of thesendto(),sendmsg() orsend() syscalls. Usingsendto() as the primary example:

structsockaddr_mctpaddr;charbuf[14];ssize_tlen;/* set message destination */addr.smctp_family=AF_MCTP;addr.smctp_network=0;addr.smctp_addr.s_addr=8;addr.smctp_tag=MCTP_TAG_OWNER;addr.smctp_type=MCTP_TYPE_ECHO;/* arbitrary message to send, with message-type header */buf[0]=MCTP_TYPE_ECHO;memcpy(buf+1,"hello, world!",sizeof(buf)-1);len=sendto(sd,buf,sizeof(buf),0,(structsockaddr_mctp*)&addr,sizeof(addr));

The network and address fields ofaddr define the remote address to send to.Ifsmctp_tag has theMCTP_TAG_OWNER, the kernel will ignore any bits setinMCTP_TAG_VALUE, and generate a tag value suitable for the destinationEID. IfMCTP_TAG_OWNER is not set, the message will be sent with the tagvalue as specified. If a tag value cannot be allocated, the system call willreport an errno ofEAGAIN.

The application must provide the message type byte as the first byte of themessage buffer passed tosendto(). If a message integrity check is to beincluded in the transmitted message, it must also be provided in the messagebuffer, and the most-significant bit of the message type byte must be 1.

Thesendmsg() system call allows a more compact argument interface, and themessage buffer to be specified as a scatter-gather list. At present no ancillarymessage types (used for themsg_control data passed tosendmsg()) aredefined.

Transmitting a message on an unconnected socket withMCTP_TAG_OWNERspecified will cause an allocation of a tag, if no valid tag is alreadyallocated for that destination. The (destination-eid,tag) tuple acts as animplicit local socket address, to allow the socket to receive responses to thisoutgoing message. If any previous allocation has been performed (to for adifferent remote EID), that allocation is lost.

Sockets will only receive responses to requests they have sent (with TO=1) andmay only respond (with TO=0) to requests they have received.

recvfrom(),recvmsg(),recv() : receive an MCTP message¶

An MCTP message can be received by an application using one of therecvfrom(),recvmsg(), orrecv() system calls. Usingrecvfrom()as the primary example:

structsockaddr_mctpaddr;socklen_taddrlen;charbuf[14];ssize_tlen;addrlen=sizeof(addr);len=recvfrom(sd,buf,sizeof(buf),0,(structsockaddr_mctp*)&addr,&addrlen);/* We can expect addr to describe an MCTP address */assert(addrlen>=sizeof(buf));assert(addr.smctp_family==AF_MCTP);printf("received %zd bytes from remote EID %d\n",rc,addr.smctp_addr);

The address argument torecvfrom andrecvmsg is populated with theremote address of the incoming message, including tag value (this will be neededin order to reply to the message).

The first byte of the message buffer will contain the message type byte. If anintegrity check follows the message, it will be included in the received buffer.

Therecv() system call behaves in a similar way, but does not provide aremote address to the application. Therefore, these are only useful if theremote address is already known, or the message does not require a reply.

Like the send calls, sockets will only receive responses to requests they havesent (TO=1) and may only respond (TO=0) to requests they have received.

ioctl(SIOCMCTPALLOCTAG) andioctl(SIOCMCTPDROPTAG)¶

These tags give applications more control over MCTP message tags, by allocating(and dropping) tag values explicitly, rather than the kernel automaticallyallocating a per-message tag atsendmsg() time.

In general, you will only need to use these ioctls if your MCTP protocol doesnot fit the usual request/response model. For example, if you need to persisttags across multiple requests, or a request may generate more than one response.In these cases, the ioctls allow you to decouple the tag allocation (andrelease) from individual message send and receive operations.

Both ioctls are passed a pointer to astructmctp_ioc_tag_ctl:

structmctp_ioc_tag_ctl{mctp_eid_tpeer_addr;__u8tag;__u16flags;};

SIOCMCTPALLOCTAG allocates a tag for a specific peer, which an applicationcan use in futuresendmsg() calls. The application populates thepeer_addr member with the remote EID. Other fields must be zero.

On return, thetag member will be populated with the allocated tag value.The allocated tag will have the following tag bits set:

• MCTP_TAG_OWNER: it only makes sense to allocate tags if you’re the tagowner

• MCTP_TAG_PREALLOC: to indicate tosendmsg() that this is apreallocated tag.

• ... and the actual tag value, within the least-significant three bits(MCTP_TAG_MASK). Note that zero is a valid tag value.

The tag value should be used as-is for thesmctp_tag member ofstructsockaddr_mctp.

SIOCMCTPDROPTAG releases a tag that has been previously allocated by aSIOCMCTPALLOCTAG ioctl. Thepeer_addr must be the same as used for theallocation, and thetag value must match exactly the tag returned from theallocation (including theMCTP_TAG_OWNER andMCTP_TAG_PREALLOC bits).Theflags field must be zero.