xaptum / hss Goto Github PK

Provide descriptions and flowcharts for common operations. Including

• Read from local buffers
• Send to peer (waiting for ACKs, ect)
• Handle closes (will have parts in read from local and send to peer)

The way HSS uses memcpy can cause issues when copying between different machines. This is necessary to address before upstreaming.

From the C99 standard

6.5.3.2 Address and indirection operators
87) Among the invalid values for dereferencing a pointer by the unary * operator are a null pointer, an address inappropriately aligned for the type of object pointed to, and the address of an object after the end of its lifetime.

In practice x86 does not care nor would our version of ARM, but other architectures like SPARC or older ARM chips will.

Take this struct (this a bug that I forgot to update when family went from 1 to 2 bytes).

struct hss_payload_connect_ip {
	enum hss_family	family; /* 2 bytes */
	__u8					resvd; /* One byte */
/* Any sane compiler will place another 1 byte pad here */
	__le16					port;
/* Padding here? */
	union hss_payload_connect_ip_addr	addr;
};

1. Structs are not packed so the compiler can add padding. Most systems would probably pad this the same way but that's not a guarantee. Between port and addr a 64-bit system may want to align to 8 byes and insert another 4-byte pad where a 32-bit system probably won't.
2. Packing the structs is not a solution, it is undefined behavior to de-reference a misaligned pointer and we would have to take special care to design structs not to be misaligned. Thats just a way to introduce problems
3. The way we transmit packets pays no attention to alignment. It occurs to me that this might be why no one else in the kernel typecasts a struct on circular buffer segment.

The solution is to stop trying to entangle our defined format with the C structs. The members should match up in width and endianness, but memcpy needs to be used instead of typecasting and named assignments. I do not think this will have a performance hit, it's just tedious.

#35 only addressed packets sent by the host and received by the device. The two directions have diverged a fair amount from eachother over time. I would recommend making device->host communications look more like the recent updates.

None of this represents a bug because the deice will only transmit the subset of the spec the host can understand.

This was brought up during the OSS talk. The device has no ability to resolve domain names and the connect commands require an IP address, it would be useful to add functionality to relay DNS resolution data between the sides or allow a connection to a domain name instead of an IP address. In a followup conversation the person remarked "In most cases, we've seen so far, IP addresses are avoided because they are difficult to change later. Also even simple DNS round robin is useful for robustness and load balancing."

The person who asked did not express an interest in adapting HSS but this is still a good feature that should be addressed if we want wide usage.

Function scm_sock_create currently passes the SCM error code back to the caller. To facilitate correct behavior this function should pass back the appropriate value from the POSIX call based on the SCM return code.

Create new command type for internal communication requests so the usb client can request information from the host. In this case we need the data from TCP sessions getsockname but there will almost certainly be others so a generic command with request data will be the best approach.

NCM provides some metadata about what Ethernet frames are inside a given USB transfer. We may have some utility for this in future applications so investigate why they do this and make room for a similar mechanism if it looks useful.

Use Hungarian notation for packet definitions.

• b: Byte
• w: Word (2 byte)
• d: Double word (4 byte)
• bm: Bitmap (arbitrary size, each bit means something)

Do not use Linux or other IDs to identify internet or transport protocol choices. Define them in the spec and have the implementer translate them to that type of connection.

Describe the USB endpoints in the documentation. This protocol is necessarily linked to sock types so describe those as well. Make sure to describe why we don't use control sockets for socket "control" methods (reordering, ect).

Current config has no dependencies, figure out which other modules are necessary as depends/selects and add them to the file.

Vendor ID is 0x02fe and should be 0x2fe0

See CDC EEM and CDC NCM docs for examples. We eventually want to submit this to be a standard protocol in the same way as these so use a similar form.

CLOSE and SHUTDOWN packets to not have room for error codes so a connection close looks identical to the device form an error code. The device needs to be told the reason for a socks close.

They are not currently used and we haven't given enough thought to their implementation to meaningfully spec it at this stage. So for the time being remove mentions from the documentation.

• Remove current mentions
• Plan future implementation

Current ACK protocols return Linux codes on error, this will not port well to Windows or other non-POSIX(ish) systems. Figure out the kind of codes we want to pass and manually define them. Provide a table to map POSIX and Windows codes to our protocol.

Device will have to manage synchronization to make sure we don't close before data is sent and similar problems. But we should move towards the more standard procedure of using a control endpoint to communicate these short (preferable low latency) commands. Rather than stacking every command into a bulk transfer, the bulk EP will become exclusively for handling write operations between the device and host.

Instead of using variable length payload packets for commands like CONNECT, use fixed size command packets up to 64-bytes long. Dispense with the immediate type and make all bulk transfers payload.

Implementers may not want to store messages in memory waiting for a reply, have ACK return the opcode of the message so endpoints can maintain a state and know what is being responded to implicitly. (eg Device sends CONNECT to host on sock 2, if it receives a SUCCESS ACK for that opcode it does not care what the actual sent message was since there cannot be two of them).